Versions Compared

Old Version 6

changes.mady.by.user Stephan Böhmig

Saved on

compared with

New Version 7

changes.mady.by.user Stephan Böhmig

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

action

Value: Create

string, Mandatory

cid

The company ID of the person. You need to specify this value.

int, Mandatory

email

The mandatory email.

string, Mandatory

login

An optional login. Only specify if you want this user to be able to login. Note that no password will be assigned at this stage.

string?, Optional

fname

First name.

string, Mandatory

lname

Last name.

string, Mandatory

title

Optional title of person, such as “Dr.”, “Mrs.” etc.

string?, Optional

role

Optional role of the person, such as “Manager”.

string?, Optional

code

Optional name abbreviation.

If not specified, the system automatically picks the initial letters of first and last name. “John Good” => “JG”

string?, Optional

phone

Optional phone number.

string?, Optional

phoneMobile

Optional mobile phone number.

string?, Optional

comments

Optional internal comments.

string?, Optional

timezone

Optional time zone. If not specified then the person inherits the time zone of the company to which he/she is attached (recommended).

To enumerate available time zones see: settings/timezones/codes

string?, Optional

cfs

Optional person-level custom fields. It contains a collection of custom fields. Example:

Code Block
"cfs": [
  { "id": 10, "t": "myvalue" },
  { "t": "My field", "t": "myvalue" }
]

You can reference custom fields by their numeric ID (see id) or their title (see t). The example above shows both approaches.

object?, Optional

active

Optional boolean. If you want the person to be able to login, you should:

  • Set active to true.

  • Set a login.

  • Optionally, set a profile.

bool?, Optional

profile

Optional integer. Use to assign a specific user profile.

If the new person has a login and is active, it is recommended to explicitly assign a user profile. If you do not do so then the system will automatically assign a user profile on your behalf. This will typically be the first profile in alphabetical order.

See User profiles to enumerate available profiles.

integer?, Optional

data

An optional free-text information. It will be returned with the results for your convenience.

string?, Optional

ExampleCreating a person without a login and the absolutely minimal required information:

Code Block
{
    "action": "Create",
    "cid": 537,
    "email": "Delete"john@john.com",
    "fname": "John",
    "pidlname": "Hendo" 
}

Creating a person with a login and a few more properties:

Code Block
{
    "action": 677"Create",
    "cid": 537,
    "login": "john.hendo",
    "email": "john@john.com",
    "fname": "John",
    "lname": "Hendo",
    "active": true,
    "profile": 22,
    "phone": "8818777272",
    "title": "CEO",
    "comments": "This is our CEO",
    "cfs": [ { "t": "Position", "datav": "justAt athe testtop" } ]
}

...

Changing a person

The JSON properties are:

cid

Company ID. This property is mandatory. You do indeed need to find out the company to which the person is attached or shall be attached.

By the way, it is not possible to change the company ID of an existing person. Once a person is attached to a company, this attachment is forever!

int, Mandatory

pid

The unique ID of the person. When deleting or updating a person you need to provide any of the 3 possible identifiers: Id, Login, Email.

int?, Optional

login

The login assigned to the person. When deleting or updating a person you need to provide any of the 3 possible identifiers: Id, Login, Email.

The login is not mandatory and a person without a login is perfectly valid in Wordbee Translator.

string, Optional

email

The email. When creating a new person you must specify the email.

string, Optional

action

Either one of:

  • Create: To create a new person.

  • Update: To update an existing person.

  • Delete: To delete an existing person.

  • ChangeOrCreate: To update the person if it exists, or otherwise to create a new person.

  • Skip: Disregard this request. With this option, no other property is mandatory.

string, Mandatory

Value: Change

string, Mandatory

cid

The company ID of the person. You need to specify this value.

int, Mandatory

pid, login, email

Use any of these three properties to uniquely identify the person to delete. The system will select in this order of priority: pid, then login, then email.

  • pid: The unique person ID. An integer.

  • login: The login of the person. This only works if the person actually was assigned a login in the first place.

  • email: The email of the person. Please note that Wordbee does not enforce unique emails!

Examples:

Code Block
{ "pid": 1000 }
or
{ "login": "john.hauser" }
or
{ "email": "john@hauser.me" }

int?, string?, string?

Mandatory

*

Specify the properties that you want to change. These are those document further above for creating persons.

Optional

data

An optional free-text information. It will be returned with the results for your convenience.

string?, Optional

Updating the comments of a person. We select the person by its unique ID.

Code Block
{
    "action": "Change",
    "cid": 537,
    "pid": 3454,
    "comments": "No more comments" 
}

Updating various properties. We select the person by its email.

Code Block
{
    "action": "Change",
    "cid": 537,
    "email": "andre@lima.com",
    
    "login": "andre.lima",
    "fname": "Andre",
    "lname": "Lima",
    "active": true,
    "profile": 22,
    "phone": "8818777272",
    "title": "CEO",
    "comments": "This is our CEO",
    "cfs": [ { "t": "Position", "v": "At the top" } ]}

If the person was not changed (values are the same) then the system will tell you so! This can happen, for example, if you submit the same request twice.

Changing or Creating a person

This is a very useful mode:

  • If the person exists then the person will be updated from your request.

  • If the person does not yet exist then it will be created.

This mode thus allows to submit updates

The big advantage over Create and Change is: You do not need to verify in advance if a person exists or not.

The JSON properties are:

action

Value: ChangeOrCreate

string, Mandatory

cid

The company ID of the person. You need to specify this value.

int, Mandatory

pid, login, email

Specify any one of the three identifiers below:

  • pid: Only specify if you have the person’s unique ID on records.

  • login: To find back a person by login or create a person with this login

  • email: To find back a person by email or create a person with this email.

If the system cannot find back the person with the identifiers above, it will proceed with the creation of a new person.

int?, string?, string?

Mandatory

*

Specify the other properties.

Important: All properties that are mandatory when creating persons must be specified.

Some mandatory,

Some optional

data

An optional free-text information. It will be returned with the results for your convenience.

string?, Optional

Update person or create if it does not yet exist:

Code Block
{
    "action": "ChangeOrCreate",
    "cid": 537,
    "email": "andre@lima.com",
    
    "login": "andre.lima",
    "fname": "Andre",
    "lname": "Lima",
    "active": true,
    "profile": 22,
    "phone": "8818777272",
    "title": "CEO",
    "comments": "This is our CEO",
    "cfs": [ { "t": "Position", "v": "At the top" } ]}

Skip person

This mode tells the system to simply disregard the request.

action

Value: Skip

string, Mandatory

data

The company ID of the person. You need to specify this value.

int, Mandatory

data

An optional free-text information. It will be returned with the results for your convenience.

string?, Optional

Example:

Code Block
{
    "action": "Skip",
    "fname": "Andre",
    "lname": "Lima",
    "data": "disregard this record!"
}

Tips & Tricks

Synchronizing from external databases

When you have an external database of persons and you want to synchronize changes into Wordbee, you may consider the following recommendations:

  • Prefer these two actions: “ChangeOrCreate” and “Delete”.

  • Use the “email” or “login” as the identifier if you do not want to store back the Wordbee person IDs in your systems.

  • If you want to create persons with a “login” it is strongly recommended that you explicitly assign the user profile (property profile). Although the system will auto-assign a default profile, it may not be the profile you want giving either too many or too little access rights.