<access-service>/api/v1/organisations/{orgGroupId}/users/import

URL structure

https://access-service.xy-company.com/api/v1/organisations/{orgGroupId}/users/import

where {orgGroupId} is the ID of an organisation.

Supported methods and overview

• POST - adds new Cocoon Data user accounts ¹ in bulk from a CSV file to an organisation (specified by orgGroupId).

Detailed description

This API endpoint adds new Cocoon Data user accounts ¹ in bulk from a CSV file to an organisation (specified by orgGroupId).

¹ If a Cocoon Data user account is not already registered on the Cocoon Data Platform, then making this request automatically creates this user account.

Supported roles and conditions

This API endpoint supports requests utilizing Cocoon Data user accounts with the following roles (as described in the Organisation Administrator's Guide) and conditions:

• Organisation administrator - when this user is a member of the organisation specified by {orgGroupId} in the request's URL.

The Cocoon Data Platform's resources available to a Cocoon Data user meeting the criteria above is determined by the access token submitted in the header of requests to this endpoint.

Required headers

The appropriate access token as the Bearer token:

• Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE0NjcwMTY2NjYsInVzZXJfbmFtZSI6ImFsZXgub...

The following header is also required in the request to allow multi-part (including binary) form data elements to be uploaded through the request:

• Content-Type: multipart/form-data

Note: It is also worth appending to this header a boundary parameter, whose string value is used to demarcate each multi-part form data element of the request (i.e. this string is not used for any other purpose throughout the entire request).
For example, to use the following string to demarcate each multi-part form data element:
-----------------------------12345678901234567890123456
assign this string value to the boundary parameter, which in turn is appended to the Content-Type: multipart/form-data header, such that this header will be:
Content-Type: multipart/form-data; boundary=-----------------------------12345678901234567890123456

Required parameters

The following required parameter must be sent in the body of the POST request, as an individual multi-part form data element:

• file - The actual data of the CSV file containing Cocoon Data user accounts to be added to the organisation. See Adding new users in bulk (from CSV) in the Organisation Administrator's Guide for more information about the preparation and requirements for your CSV file.
  Example (uploading a CSV file containing user accounts):

  -----------------------------12345678901234567890123456
  Content-Disposition: form-data; name="file"; filename="UsersToImport.csv"
  Content-Type: text/csv
  
  {YOUR ACTUAL CSV DATA HERE}
  -----------------------------12345678901234567890123456

Returns

If the request succeeded, then an HTTP response status 200 OK is returned.

For successful requests only, a JSON-formatted response containing the following members is also returned:

• success - A boolean value that indicates whether (true) or not (false) any of the user accounts specified in the CSV file were successfully imported into the organisation specified by {orgGroupId} in the URL.
• message - An member containing the internationalization (I18N) property key/code ² for a message indicating the number of user accounts successfully imported into this organisation (i.e. hard-coded in the Cocoon Data Platform), as the sub-member:
  • i18n - A member containing the I18N code ² for the message indicating the number of user accounts successfully imported into this organisation, as sub-members:
    • message - The message itself, in the language that the user account (whose access token is submitted in the request to this endpoint) is configured for (via their I18N settings).
    • code - The I18N code for this message's value, beginning with server.userimportjob.imported. This I18N code could include the substring plural, single or none.
    • arguments - An array containing any arguments/variables that constitute the value of the I18N code for use in the message's value above. When the I18N substring is plural, this array contains a sub-array whose values are the argument usernumber, followed by the number of users who were successfully imported into the organisation.
• errors - An array of strings, each one describing an error encountered when importing a new Cocoon Data user to the Cocoon Data Platform from the CSV file. An member containing the internationalization (I18N) property key/code ² for a message indicating the number of user accounts successfully imported into this organisation (i.e. hard-coded in the Cocoon Data Platform), as the sub-member:
  • i18n - A member containing the I18N code ² for the message indicating the number of user accounts successfully imported into this organisation, as sub-members:
    • message - The message itself, in the language that the user account (whose access token is submitted in the request to this endpoint) is configured for (via their I18N settings).
    • code - The I18N code for this message's value, beginning with server.userimportjob. This I18N code could include one of these substrings:
      • invaliduserrole.exclusionviolation
      • invaliduserrole.cannotdowngrade
      • invaliduserrole.toofewroles
      • invaliduserrole.toomanyroles
      • invaliduserrole.invalidrole
      • invaliduserrole.missing
      • invaliduserrole.unsupported
      • invaliduserrole.mappingerror
      • invaliduserrole.badcsvformat
      • invaliduserrole.savefailed
      • formaterrors
      • formaterrors.validatedrowcontent
      • bizlogicerrors
      • defaultplan.missing
      • orgquotaexceeded
      • createuser.failed
    • arguments - An array containing any arguments/variables that constitute the value of the I18N code used in the message's value above. When the I18N substring is:
      • invaliduserrole.exclusionviolation - this array contains a sub-array whose values are the argument exclusionViolations.
      • invaliduserrole.cannotdowngrade - this array contains a sub-array whose values are the arguments originalrole and downgraderole, whose respective values are strings representing the role the user originally had in this organisation, followed by the new (i.e. downgraded) role being applied to this user.
      • invaliduserrole.toofewroles - this array contains a sub-array whose values are the argument min, followed by the minimum number of roles that must to be applied to the user.
      • invaliduserrole.toomanyroles - this array contains a sub-array whose values are the argument max, followed by the maximum number of roles that can to be applied to the user.
      • invaliduserrole.missing - this array contains a sub-array whose values are the argument useremail, followed by the email address of the user to be imported into the organisation, who did not have a role specified in the CSV file.
      • invaliduserrole.unsupported - this array contains a sub-array whose values are the arguments rolename and useremail, whose respective values are strings representing the unsupported role for the user (represented by their email address) in the CSV file.
      • invaliduserrole.mappingerror - this array contains a sub-array whose values are the arguments role and email, whose respective values are strings representing role being applied to the user (represented by their email address) in the CSV file.
      • defaultplan.missing - this array contains a sub-array whose values are the argument orgGrpName, followed by the name of the organisation which does yet not have a default plan configured.
      • createuser.failed - this array contains a sub-array whose values are the argument useremail, followed by the email address of the user which the Cocoon Data Platform failed to create for an unknown reason.
  ² Your client application can exploit the Cocoon Data Platform's I18N features, by initially downloading the relevant language bundles (from the the Cocoon Data Platform), then using the i18n code (and if applicable, arguments) values above to extract the property values derived from these language bundles for use in your client application. For more information about the Cocoon Data Platform's I18N features, see Managing internationalization in the SafeShare Administrator's Guide.
  Example (response):

  {  
      "success": true,
      "message": {
          "i18n": {
              "message": "2 users successfully imported.",
              "code": "server.userimportjob.imported.plural",
              "arguments": [
                  [
                      "usernumber",
                      "2"
                  ]
              ]
          }
      },
      "errors": [
          {
              "i18n": {
                  "message": "Role 'Ad hoc' is not supported in user import for 'adhoc.user@xy-company.com'",
                  "code": "server.userimportjob.invaliduserrole.unsupported",
                  "arguments": [
                      [
                          "rolename",
                          "Ad hoc"
                      ],
                      [
                          "useremail",
                          "adhoc.user@xy-company.com"
                      ]
                  ]
              }
          }
      ]
  }