Set Current State With Template

This endpoint allows you to set a user’s current state using a template. This is useful for quickly applying a predefined state to a user, which can help in managing their workload and ensuring that they are in the correct state for their tasks.

Endpoint URL

(see more)

[POST] https://[address]:[port]/rest/ExternalSetCurrentStateWithTemplate

The endpoint supports both Totalview user IDs and email addresses.

Calling The Endpoint

You must provide the following parameters along with the required header:

Parameters

  • UserID - note: this field can be set to a userid or email

  • TemplateShortName - what template to use for the state

  • Comment - (Optional) The comment to be added to the state

  • EndDate - (Optional) The specific end date in UTC. If null then the default duration defined in the template will be used. Format: yyyy-MM-ddTHH:mm:ss

  • Attachment - (Optional) Specify attachments for this state in XML

Headers

  • x-api-key - This is the API key from the WCF Connector in Totalview Admin (see more)

Requirements for Attachment

  1. The root of the XML has to be of type ATTACHMENTS

    1. ATTACHMENTS can be sent without any child elements:

      <ATTACHMENTS />

  2. If ATTACHMENTS has descendants, the first level descendants should be of type ATTACHMENT

    1. ATTACHMENT elements have four required attributes:

      1. CAPTION is the attachment section caption shown in F5/F6 (in the Totalview Client).

      2. ATTACHMENTID is a unique id for this attachment. This must be unique for each Attachment connector.

      3. PROVIDER is the name of the Attachments connector in Totalview

      4. VERSION is the version of the XML

    2. All ATTACHMENT elements require at least one FIELD descendant

      1. FIELD elements have four required attributes:

        1. FIELDID is a unique id for this ATTACHMENTDEFINITION.

        2. CAPTION is the label for the field.

        3. DATAID corresponds to the ID of the ATTACHMENTDEFINITION in XML, SQL, or Business Central

        4. DATAVALUE corresponds to the VALUE of the ATTACHMENTDEFINITION in XML, SQL, or Business Central

    <ATTACHMENTS>
   <ATTACHMENT CAPTION="Case" ATTACHMENTID="XMLCASE" PROVIDER="Attachment" VERSION="1.1">
      <FIELD FIELDID="CUSTOMER" CAPTION="Customer" DATAID="1000" DATAVALUE="Jackson Car Sale">
         <FIELD FIELDID="CASE" CAPTION="Case" DATAID="1001" DATAVALUE="Totalview 3 TRS">
            <FIELD FIELDID="ACTIVITY" CAPTION="Activity" DATAID="1002" DATAVALUE="Installation">
               <FIELD FIELDID="SUBACTIVITY" CAPTION="Sub activity" DATAID="1003" DATAVALUE="Server setup" />
               <FIELD FIELDID="WORKTYPE" CAPTION="Work type" DATAID="1007" DATAVALUE="On location" />
            </FIELD>
         </FIELD>
      </FIELD>
   </ATTACHMENT>
</ATTACHMENTS>

Finding The UserID / Email Address

You can find a user’s UserID and Email by right-clicking on the user in the Totalview Client

../../../_images/finding-user-details.png

Finding The Template Short Name

  1. Open Totalview Admin

  2. Navigate to the Template view

  3. Click on any of the templates

    • The templateShortName is the first field called Id

Example: Calling the Endpoint Using cURL

curl --location --request POST 'https://localhost:5039/rest/ExternalSetCurrentStateWithTemplate' \
--header 'x-api-key: {BF1E7B12-F085-435D-8FF7-412D88692FC4}' \
--header 'Content-Type: application/json' \
--data '{
   "userID": "test@domain.com",
   "templateShortName":"in"
}'

curl --location --request POST 'https://localhost:5039/rest/ExternalSetCurrentStateWithTemplate' \
--header 'x-api-key: {BF1E7B12-F085-435D-8FF7-412D88692FC4}' \
--header 'Content-Type: application/json' \
--data '{
   "userID": "test@domain.com",
   "templateShortName":"in",
   "comment":"Production Support",
   "endDate": "2025-05-02T17:00:00",
   "attachment": "<ATTACHMENTS><ATTACHMENT CAPTION=\"Case\" ATTACHMENTID=\"XMLCASE\" PROVIDER=\"Attachment\" VERSION=\"1.1\"><FIELD FIELDID=\"CUSTOMER\" CAPTION=\"Customer\" DATAID=\"1000\" DATAVALUE=\"Jackson Car Sale\"><FIELD FIELDID=\"CASE\" CAPTION=\"Case\" DATAID=\"1001\" DATAVALUE=\"Totalview 3 TRS\"><FIELD FIELDID=\"ACTIVITY\" CAPTION=\"Activity\" DATAID=\"1002\" DATAVALUE=\"Installation\"><FIELD FIELDID=\"SUBACTIVITY\" CAPTION=\"Sub activity\" DATAID=\"1003\" DATAVALUE=\"Server setup\" /><FIELD FIELDID=\"WORKTYPE\" CAPTION=\"Work type\" DATAID=\"1007\" DATAVALUE=\"On location\" /></FIELD></FIELD></FIELD></ATTACHMENT></ATTACHMENTS>"
}'

Example of a successful call

{
   "ExternalSetCurrentStateWithTemplateResult": {
      "Error": "",
      "Status": true
   }
}

Example of a failed call

{
   "ExceptionType": "InvalidParameter",
   "Message": "Template In not found"
}