This API is intended only for use by GOSS developers as the first stage in user linking product development. It is liable to change and should not be incorporated into production environments with real users.
This API manages the types of links that can be created between users. No userLinkTypes exist in the database until they have been created.
When a userLinkType is created an ID is returned in the response. This ID is used in all other methods and when managing links between users with userLinking_userLinks.
Authentication
All requests need the username and password of an iCM user. These can be provided directly or via an API key's "default credentials".
See End Point this Object for information about supplying an API key when calling a worker from an End Point, API Server Security for information about keys and default credentials, and the methods below for examples.
Name and ID
All link types have a name, set when the type is created, and an ID generated by the worker.
Direction and Cardinality
When you create a link type you must also set its cardinality. Then, when you create a link between users, you set the link type and the direction of that link (either to or from the user).
Once users are linked by a particular type and direction, attempts to create additional links to or from the same user of the same type are checked against the cardinality of existing links for conflicts.
The four cardinality types are:
ONE_TO_ONE - A user may have a single one-to-one link of a particular type linking to it and from it
userA cannot link to userD as it already has a one-to-one link of this type from it. userC can link to userA. userB cannot link to or from anyone else
ONE_TO_MANY - A user may have a single one-to-many link of a particular type linking to it, and any number linking from it
userA can link to many users. userD cannot link to userC using this one-to-many type as userC already has a link from userA
MANY_TO_ONE - A user may have a single many-to-one link of a particular type linking from it, and any number linking to it
Many users can link to userA. userC cannot link to userD as it is already linked to userA by this many-to-one link
MANY_TO_MANY - A user can have any number of these links to it and/or from it
Logging
Creating, deleting and updating link types is recorded in iCM's security log.
Methods
Note that all request parameters are passed to the method in a "payload" object. See the examples below.
userLinking_userLinkTypes_create
Creates a userLinkType.
Request Parameters
| Name | Type | Description |
|---|---|---|
| name | String | Required. A name for this userLinkType |
| cardinality | String | Required. One of ONE_TO_ONE, ONE_TO_MANY, MANY_TO_ONE, MANY_TO_MANY |
| comment | String | Optional. An optional comment |
function(params, credentials) {
let linkType = this.callWorkerMethod("icmapi", "userLinking_userLinkTypes_create", {
payload: {
name: "testManyToOne",
cardinality: "MANY_TO_ONE",
comment: "Many to one testing"
}
}, {
options: {
apiKey: "<Your API Key>"
}
});
return linkType;
}
Response - Success
| Name | Type | Description |
|---|---|---|
| id | Integer | The ID of the created userLinkType |
| name | String | As supplied |
| cardinality | String | As supplied |
| comment | String | As supplied |
{
"id": 743,
"result": {
"id": 8,
"name": "testManyToOne",
"cardinality": "MANY_TO_ONE",
"comment": "Many to one testing"
},
"jsonrpc": "2.0"
}
Response - Error
Returned when the name already exists.
{
"id": "_1",
"error": {
"code": -32602,
"data": "Conflict",
"message": "Conflict"
},
"jsonrpc": "2.0"
}
userLinking_userLinkTypes_delete
Deletes a userLinkType. Note that when a userLinkType is deleted, all links between users of this type are also deleted.
Request Parameters
| Name | Type | Description |
|---|---|---|
| id | Integer | Required. The ID of the userLinkType to delete |
function(params, credentials) {
let linkType = this.callWorkerMethod("icmapi", "userLinking_userLinkTypes_delete", {
payload: {
id: 10
}
}, {
options: {
apiKey: "<Your API Key>"
}
});
return linkType;
}
Response - Success
None.
{
"result": null,
"id": "_1",
"jsonrpc": "2.0"
}
Response - Error
Returned when the userLinkType couldn't be found.
{
"id": "_1",
"error": {
"code": -32602,
"data": "NotFound",
"message": "NotFound"
},
"jsonrpc": "2.0"
}
userLinking_userLinkTypes_get
Returns a single userLinkType by ID.
Request Parameters
| Name | Type | Description |
|---|---|---|
| id | Integer | Required. The ID of the userLinkType |
function(params, credentials) {
let linkType = this.callWorkerMethod("icmapi", "userLinking_userLinkTypes_get", {
payload: {
id: 8
}
}, {
options: {
apiKey: "<Your API Key>"
}
});
return linkType;
}
Response - Success
The requested userLinkType.
| Name | Type | Description |
|---|---|---|
| id | Integer | The ID of the userLinkType |
| name | String | The name |
| cardinality | String | The cardinality |
| comment | String | The comment |
{
"id": 743,
"result": {
"id": 8,
"name": "testManyToOne",
"cardinality": "MANY_TO_ONE",
"comment": "Many to one testing"
},
"jsonrpc": "2.0"
}
userLinking_userLinkTypes_getAll
Gets all userLinkTypes that match the supplied filters and paging.
Request Parameters
| Name | Type | Description |
|---|---|---|
| filters | Object | Optional. Not setting a filter (or providing an empty filter object) will return all userLinkTypes |
| filters.names | Array <string> | The names of the userLinkTypes to return |
| pagination | Object | Optional. The start position and length of results to return |
| pagination.start | Integer | The start position (zero based) |
| pagination.length | Integer | The number to return |
This example returns the first three userLinkTypes.
function(params, credentials) {
let getAll = this.callWorkerMethod("icmapi", "userLinking_userLinkTypes_getAll", {
payload: {
filters: {},
pagination: {
start: 0,
length: 3
}
}
}, {
options: {
apiKey: "<Your API Key>"
}
});
return getAll;
}
This example returns the named link types.
function(params, credentials) {
let getAll = this.callWorkerMethod("icmapi", "userLinking_userLinkTypes_getAll", {
payload: {
filters: {
names: ["timOneToMany", "timOneToOne"]
},
pagination: {}
}
}, {
options: {
apiKey: "<Your API Key>"
}
});
return getAll;
}
Response - Success
An array of userLinkTypes that match the filters and pagination, where each userLinkType has the following properties.
| Name | Type | Description |
|---|---|---|
| id | Integer | The ID of the userLinkType |
| name | String | The name |
| cardinality | String | The cardinality |
| comment | String | The comment |
{
"id": 477,
"result": [{
"id": 4,
"name": "timOneToMany",
"cardinality": "ONE_TO_MANY",
"comment": null
}, {
"id": 5,
"name": "timOneToOne",
"cardinality": "ONE_TO_ONE",
"comment": "One to one test"
}],
"jsonrpc": "2.0"
}
userLinking_userLinkTypes_update
Updates an existing userLinkType. The payload is the same as that of create, with the addition of the ID of the userLinkType to update.
When updating the cardinality of a link type all existing user links are checked and the update will fail if the new cardinality would violate existing links.
Request Parameters
| Name | Type | Description |
|---|---|---|
| id | Integer | Required. The ID of the userLinkType to update |
| name | String | Required. A name for this userLinkType |
| cardinality | String | Required. One of ONE_TO_ONE, ONE_TO_MANY, MANY_TO_ONE, MANY_TO_MANY |
| comment | String | Optional. An optional comment |
function(params, credentials) {
let linkType = this.callWorkerMethod("icmapi", "userLinking_userLinkTypes_update", {
payload: {
id: 8,
name: "new name",
cardinality: "MANY_TO_ONE",
comment: "new comment"
}
}, {
options: {
apiKey: "<Your API Key>"
}
});
return linkType;
}
Response - Success
None.
{
"result": null,
"id": "_1",
"jsonrpc": "2.0"
}
Response - Error
In this example the change to the cardinality would have caused a conflict with existing links between users.
{
"id": "_1",
"error": {
"code": -32602,
"data": "Conflict",
"message": "Conflict"
},
"jsonrpc": "2.0"
}
Share this page
