persons/io/updates (POST)

This method lets you create, update or delete one or more persons.

A typical use case is: Synchronize an external directory and import changes to Wordbee Translator. Create new persons, update existing persons or delete persons.

This method is an asynchronous operation: Asynchronous operations

URL

CODE

(POST) /api/persons/io/updates

PARAMETERS

The body must contain a JSON object with these properties:

fileToken	The token that references the JSON array with all updates (your requests for creation, change or deletion of persons). Use media/upload to upload JSON and obtain the token. The JSON payload is an array of update requests, see Person update request (Object)	string, Mandatory
readonly	Optional. If not specified, then value is set to false. false: Default value. Any changes are committed. true: To test if your payload is valid. The system checks all data but does not commit changes to the system. Please use the read-only mode for development or testing only. It should not be used in production.	bool, Optional
callbackurl, callback	Specify a URL which will be called upon success or failure of operation. This makes polling for operation status unnecessary. See Callbacks (with asynchronous operations)	Optional
cfid	Optional. By default, persons are uniquely identified by either the person ID, the login or the email. It is your choice. Although not recommended, you may have decided to use a person custom field as the unique identifier. If this is the case, then set the numeric identifier for that person custom field into this property. When you then submit person change requests, you MUST include the persons' custom field value. Otherwise, the system would not be able to find back people to update.	int?, Optional

The JSON payload (which is referenced by the file token) is an array of update requests: Person update request (Object) . Example:

CODE

[
  { "action": "Change", .... },                 To change an existing person
  { "action": "Create", .... },                 To create a new person
  { "action": "ChangeOrCreate", .... },         To change person if exists or create if not yet exists.
  { "action": "Delete", .... },                 To delete a person
  { "action": "Skip", .... },                   A request that is disregarded
]

RESULTS

The API method returns an Asynchronous operation result:

JS

{
  "trm": {
    "requestid":32230,
    "status":"Waiting",
    "statusText":"Waiting..."
  }
}

You can poll the status or use the callback parameter. When the operation is complete, the results are in the custom property

JSON

{
    "trm": {
        "requestid": 32230,
        "isbatch": false,
        "status": "Finished",
        "statusText": "Finished!"
    },
    "custom": {
        "filetokenLog": "97ba14d5cccc4d29b531456002dc3da2",
        "summary": {
            "readonly": false,
            "count": 4,
            "success": 4,
            "failed": 0,
            "created": 1,
            "updated": 2,
            "deleted": 1
        }
    }
}

The custom property is a JSON object:

filetokenLog	Call method media/get/{token} with this token to get the detailed update log. This log is a JSON array. It contains all your requests with detailed status and error information: See Person update result (Object).	string
readonly	Same as input parameter. If true then no changes were actually committed.	bool
count	Total number of your change requests in payload.	int
success	Total change requests that were applied with success.	int
failed	Total change requests that failed.	int
created	Total persons newly created. The count included in success value. Creation fails if the update request is invalid or the person already exists. Errors are indicated in the log.	int
updated	Total persons that were updated. The count included in success value. Updates fail if the update request is invalid, the person does not exist or no property of the person was actually modified. Errors are indicated in the log.	int
deleted	Total persons that were deleted. The count included in success value. Deletions fail if the update request is invalid or the person does not exist. Errors are indicated in the log.	int

EXAMPLES

We construct a payload with a deletion, an update and a creation request:

CODE

[
{
    "action": "Delete",
    "pid": 677,
    "cid": 537,
    "data": "we want to delete this person"
},
{
    "action": "Update",
    "pid": 387,
    "cid": 1001,
    "phone": "0199973672",
    "data": "we want to update the phone number"
},
{
    "action": "Create",
    "cid": 1001,
    "fname": "Alex",
    "lname": "Nowhere",
    "email": "alex@nowhere.com"
    "data": "we want to create a new person. without a login in this example."
}
]

We now upload the payload above using media/upload. The method returns a token which we need for the next step.

CODE

POST /api/media/upload
BODY: multipart attachment of the JSON payload

We finally submit the updates:

CODE

POST /api/persons/io/updates
BODY:
{  
    "fileToken": "178eee3996bd4898b31da69a4fe5b206"
}

This returns the status of the asynchronous operation.

Now poll for completion every couple of seconds.
We can also include the URL callback parameter in the payload to notify us. This makes it unnecessary to waste API calls with polling!

You should read about these mechanisms here: Asynchronous operations

When the operation is finished, we get:

CODE

{
    "trm": {
        "requestid": 11230,
        "isbatch": false,
        "status": "Finished",
        "statusText": "Finished!"
    },
    "result": {
        "items": []
    },
    "custom": {
        "filetokenLog": "97ba14d5cccc4d29b531456002dc3da2",
        "summary": {
            "readonly": false,
            "count": 3,
            "success": 3,
            "failed": 0,
            "created": 1,
            "updated": 1,
            "deleted": 1
        }
    }
}

If you need it, you can download the detailed log:

CODE

GET /api/media/get/97ba14d5cccc4d29b531456002dc3da2

The content is a JSON array containing your requests with status and error information. See details at Person update request (Object)