Data Types
All data is sent and received as JSON.
- Output: The formatting of values in the responses.
- Input: The formatting of input parameters of requests.
- References: Composition of references in the responses.
- Attachments: Composition of attachments in the requests.
Output
- boolean
- native
"known_error": true
- currency
- string: one of the currencies defined in the enumeration
"currency": "usd"
- custom fields
- array of hashes: each hash has keys
id
andvalue
"custom_fields": [
{"id": "first_name", "value": "Howard"},
{"id": "last_name", "value": "Tanner"}
]
- date
- string: yyyy-mm-dd
"start_date": "2011-06-24"
- datetime
- string: yyyy-mm-ddThh:mm
"start_at": "2010-12-30T23:00"
ISO 8601 format, with a minutes resolution, without timezone.
- decimal
- string: number with decimals, separated by a dot (.)
"cost_per_hour": "120.5"
- duration
- integer: with resolution in minutes
"response_target": 240
- enum
- string: one of the options defined for the enumeration
"status": "registered"
- float
- native
"rate": 3.2313
- integer
- native
"nr_of_cores": 3
- null
- native: all blank fields are included as
null
instead of being omitted"solved_at": null
- reference
- hash: composed of multiple values, or null if the reference is not filled out
"team": {"id": 12, "name": "Service Desk"}
"team": null
- string, text
- native
"name": "Windows for Sales Tracking Production"
- timestamp
- string: yyyy-mm-ddThh:mm:ssZ
"completed_at": "2010-01-05T23:00:00Z"
ISO 8601 format, with a seconds resolution, with timezone.
- time of day
- string: hh:mm
"time_from": "08:30"
In military format. 00:00 = midnight at the start of the day, 12:00 = noon, 24:00 = midnight at the end of the day
- time zone
- string: one of the time zones defined in the enumeration
"time_zone": "Central Time (US & Canada)"
Input
- attachments
- An array of references to uploaded file attachments
- boolean
- Truthy values are
1
,T
,Y
,TRUE
,YES
,ON
. These values are case insensitive, sotrue
,trUE
,tRue
are all treated as truthy values. Falsy values are anything else, like:false
,f
,FALSE
,F
,0
?known_error=true
- enum
- One of the options defined for the enumeration
?status=registered
- date
- yyyy-mm-dd
?start_date=2011-06-24
- datetime
- yyyy-mm-ddThh:mm
?start_at=2010-12-30T23:00
ISO 8601 format (with a minutes resolution, without timezone)
- decimal, float
- any number with decimals, separated by a dot (.)
?rate=3.2313
- duration
- integer: with resolution in minutes
?response_target=150
Alternatively it accepts a string in the format
hhh:mm
, for example:?response_target=2:30
- integer
- any integer (0, 1, 2, …)
?nr_of_cores=3
- null
- all blank fields should be omitted from the input
- reference
- the
id
of the referenced resource, always append_id
to the field name?team_id=12
For arrays of references always append
_ids
to the field name
"ci_ids": [1763, 1764]
- string, text
- any value
?name=Windows%20for%20Sales%20Tracking%20Production
- timestamp
- yyyy-mm-ddThh:mm:ssZ
?completed_at=2010-01-05T23:00:00Z
ISO 8601 format (with a seconds resolution, with timezone)
- time of day
- hh:mm
?time_from=08:30
In military format. 00:00 = midnight at the start of the day, 12:00 = noon, 24:00 = midnight at the end of the day
- time zone
- any valid time zone identifier listed in one of the following sources:
Time zone values from the Time Zone Database are mapped onto the enumeration of time zones in R-Service by their UTC offset.
?time_zone=Europe/Amsterdam
References
A reference to another resource is composed of one or more of the following fields.
Note: In the input, use only the id
of the referenced resource and append _id
to the field name, e.g. ?team_id=12
.
For fields that contain an array of references as input, use the singular field name and append _ids
, e.g. service_instance_ids
for ‘service_instances’.
ID
All references contain an id
property with which the details of the resource can be retrieved using a separate API call.
Note that when a record is opened in the R-Service user interface, the id
can be found in the Address bar of the browser. It is the unique identifier at the end of the URL. The id
of an account can be found in the user interface by going to the Account Overview section of the Settings console.
For aggregated references (arrays of ~) an id
is not returned. Instead, all available fields are contained in aggregated references so that an id
is not needed.
Display Properties
The reference will always contain the properties necessary to display the (list of) reference(s) to the end-user.
In most cases this will expose the name
and/or subject
properties, but there are some exceptions like
label
for Configuration Item references.
Account
When the account of the referenced resource is different from the account of the authenticated user,
the account
reference will be provided. The account
field is itself a reference and will always only
show name
and id
. The name
is intended as a display property for the end-user. The id
can be used to switch to that account if appropriate, see Multiple Accounts.
If a resource or reference to a resource does not expose an account
field, the account of the resource is equal to the account of the authenticated user.
The following example shows a request that is completed by a member of the Service Desk team from a different account (Virtual Support).
$ curl -H "Authorization: Bearer <oauth-token>" https://api.r-service.tech/v1/requests/70384
Status: 200 OK
{
"id": 70384,
"status": "completed",
"service_instance": {
"name": "Time Off Request Production",
"id": 97
},
"team": {
"name": "Service Desk",
"account": {
"name": "VirtualSupport",
"id": "virtualsupport"
},
"id": 2
},
"member": {
"name": "Krish Hanuang",
"account": {
"name": "VirtualSupport",
"id": "virtualsupport"
},
"id": 16
}
}
Not all request fields are shown above to keep the example simple.
Source ID
When references to resources with a Source ID are retrieved from the API, the sourceID
field will always be provided.
$ curl -H "Authorization: Bearer <oauth-token>" https://api.r-service.tech/v1/requests?per_page=1
Status: 200 OK
[
{
"subject": "NewRequest",
"category": "compliment",
"status": "assigned",
"sourceID": "N1C3AP1"
}
]
Not all request fields are shown above to keep the example simple.
See source for more information on the usage of the sourceID
field.
Disabled
In case a referenced resource is disabled, the disabled: true
property will be provided. When a referenced resource
is enabled, the disabled
property is omitted.
$ curl -H "Authorization: Bearer <oauth-token>" https://api.r-service.tech/v1/services/23
Status: 200 OK
{
"id": 23,
"name": "Short Term Production Planner",
"created_at": "2016-03-10T02:05:27-06:00",
"updated_at": "2016-03-10T02:10:51-06:00",
"sourceID": null,
"support_team": {
"name": "Application Development",
"id": 7
},
"provider": {
"name": "Widget Data Center, External IT",
"id": 30,
"disabled": true
}
}
Attachments
Various rich text fields in R-Service can hold attachments. They may contain inline image or video files, and some of them can have attachments listed externally, in which case in the R-Service UI these are displayed at the bottom of the text represented with a paperclip in front of each attachment.
Adding attachments and inline image or video files to rich text fields is a three-step process:
- Get access to the R-Service storage facility
- Upload the files
- Add references to the uploaded files to a rich text field
These steps are explained in more detail hereunder for a scenario where a request is created with an attachment linked to the first note. For this example you will need a Personal Access Token with Create access to Requests.
Tip: Using the one of the R-Service API clients (SDKs) can make the process to upload attachments easier. The SDKs have specialized functionality to facilitate the steps described below. Please see the relevant documentation of the SDK for ruby or the .Net SDK for more details.
Remarks:
- Depending on your environment (Windows or UNIX), the syntax of the curl commands hereunder will be slightly different. On a UNIX system , you need to escape the
$
sign like-F "key=attachments/5/.../\${filename}" \
. On a Windows system you need to remove the backslash\
at the end of each line, use double quotes, and escape any quotes within the double quotes.
Step 1. Get access to the R-Service storage facility
$ curl -H "Authorization: Bearer <oauth-token>" \ -H "X-4me-Account: <accountID>" \ -X GET \ "https://api.r-service.tech/v1/attachments/storage"
The response will contain the storage upload details:
Status: 200 OK
{
"size_limit": 2147483648,
"allowed_extensions": [
"csv",
"gif",
"png",
"log",
"pdf"
],
"provider": "s3",
"upload_uri": "https://R-Service.s3-accelerate.dualstack.amazonaws.com/",
"s3": {
"acl": "private",
"key": "attachments/5/.../${filename}",
"policy": "eyJ...V19",
"success_action_status": 201,
"x-amz-algorithm": "AWS4-HMAC-SHA256",
"x-amz-credential": "AKIA...aws4_request",
"x-amz-date": "20201115T000000Z",
"x-amz-server-side-encryption": "AES256",
"x-amz-signature": "5a0...ae5"
}
}
In an on-premise environment the storage upload details might look like this instead:
Status: 200 OK
{
"size_limit": 20971520,
"allowed_extensions": [
"csv",
"gif",
"png",
"log",
"pdf"
],
"provider": "local",
"upload_uri": "https://api.example.com/v1/attachments",
"local": {
"key": "attachments/5/.../${filename}",
"x-R-Service-expiration": "2020-11-30T02:18:17Z",
"x-R-Service-signature": "6dd...d0f"
}
}
Step 2. Upload the files
Upload the actual file(s) to the R-Service storage facility. Post the file(s) to the value presented in upload_uri, and post all parameter presented in the s3
or local
scope, preceded by the Content-Type of the file, and provide the file data last. For example:
$ curl -F "Content-Type=plain/text" \ -F "acl=private" \ -F "key=attachments/5/.../\${filename}" \ -F "policy=eyJ...V19" \ -F "success_action_status=201" \ -F "x-amz-algorithm=AWS4-HMAC-SHA256" \ -F "x-amz-credential=AKIA...aws4_request" \ -F "x-amz-date=20201115T000000Z" \ -F "x-amz-server-side-encryption=AES256" \ -F "x-amz-signature=5a0...ae5" \ -F "file=@helloworld.txt" \ "https://R-Service.s3-accelerate.dualstack.amazonaws.com/"
Or, in an on-premise environment:
$ curl -H "Authorization: Bearer <token>" \ -H "X-4me-Account: <accountID>" \ -F "Content-Type=plain/text" \ -F "key=attachments/5/.../\${filename}" \ -F "x-R-Service-expiration=2020-11-30T02:18:17Z" \ -F "x-R-Service-signature=6dd...d0f" \ -F "file=@helloworld.txt" \ "https://api.example.com/v1/attachments"
Remarks:
- cURL interprets
-F “file=@...”
and reads thehelloworld.txt
from your disk (located in the directory where curl is executed) and sends it as form-encoded data to the server. - The response in the s3 scope needs some reformatting to be used in a curl statement. Remove the comma
,
between parameters and make sure the parameters are preceded by-F
. The parameter is formatted as"attribute=value"
instead of"attribute": "value"
. Make sure to format"success_action_status": 201
, as-F "success_action_status=201"
.
The response from the above command might look like this:
Status: 201 Created
<?xml version="1.0"?> <PostResponse> <Location>https://R-Service.s3-accelerate.dualstack.amazonaws.com/attachments%2F5%2F2020%2F11%2F15%2F6%2F1605413834-431xxxc1be%%2Fhelloworld.txt</Location> <Bucket>R-Service</Bucket> <Key>attachments/5/2020/11/15/6/1605413834-431xxxcc1be/helloworld.txt</Key> <ETag>"9008d115b2d05a7ca6b495fd0cb998df"</ETag> </PostResponse>
Or, in an on-premise environment:
Status: 200 OK
{
"key": "attachments/5/.../helloworld.txt"
}
Step 3. Add references to the uploaded files to a note
Create the new request and add all attachments in the note_attachments
parameter:
$ curl -H "Authorization: Bearer <token>" \ -H "X-4me-Account: <accountID>" \ -X POST \ -d '{ "requested_for_id": 51, "subject": "Test", "category": "other", "note": "Attachment test", "note_attachments": [ {"key": "attachments/5/.../helloworld.txt", "filesize": "16"} ] }' \ "https://api.r-service.tech/v1/requests"
Remarks:
- The value of
key
that is passed into the notes_attachments parameter should match the string from the<Key>...</Key>
XML response. In an on-premise environment it should match the valuekey
that was in the JSON response. - The
filesize
parameter is optional. - You will need to add the other parameters for creating a valid Request, such as
requested_for_id
andcategory
, see Create a Request.
Inline attachments
To add an inline attachment to a rich text field the same process as described above is followed, except in the last step the attachment needs to be marked as inline
, and a reference needs to be added within the rich text field using the special markdown syntax: ![](<key>)
. For example:
$ curl -H "Authorization: Bearer <token>" \ -H "X-4me-Account: <accountID>" \ -X POST \ -d '{ "requested_for_id": 51, "subject": "Test", "category": "other", "note_attachments": [ {"key": "attachments/5/.../helloworld.txt", "inline": true, "filesize": "16"} ], "note": "This is an inline attachment ![](attachments/5/.../helloworld.txt)" }' \ "https://api.r-service.tech/v1/requests"
Removing an attachment
To remove an attachment from a field, use the _destroy
attribute.
For example, suppose that the information
field of person 123
has an attachment with key attachments/5/.../helloworld.txt
. To remove it, execute the following:
$ curl -H "Authorization: Bearer <token>" \ -H "X-4me-Account: <accountID>" \ -X PATCH \ -d '{ "information_attachments": [ {"key": "attachments/5/.../helloworld.txt", "_destroy": true } ] }' \ "https://api.r-service.tech/v1/people/123"