14 Rating API

14.1 Overview

The Rating API enables customers with external systems to create and manage user records and user access rights for Coresystems FSM applications.

For information on customizing the rating email and other topics, please refer to the Rating API FAQ Page.


14.1.2 Rating API in Swagger

To preview Rating API functionality, you may use the Coresystems Rating API Swagger implementation.


14.2 Access

The Rating API uses Oauth 2.0 for authentication. This token is then used in the Authorization header as the bearer.

Attention: In order to receive an access token, you must have ADMINISTRATOR or SUPERUSER privileges.

14.2.1 Get Access Token

The following example shows how to get the access token for a Cloud Account or a Company User:


Cloud Account


The following example is an example of authentication for a Coresystems Cloud account with access to all companies within the account:


POST https://auth.coresuite.com/api/oauth2/v1/token HTTP/1.1

Host et.dev.coresuite.com
Authorization Basic dGVzdDpzZWNyZXQ=
Content-Type application/x-www-form-urlencoded

grant_type=password&username=cym&password=passwordExample123


Company User


The following example of authentication for a company user, with access to companies controlled by existing subscription and permission settings:


POST https://auth.coresuite.com/api/oauth2/v1/token HTTP/1.1

Host et.dev.coresuite.com
Authorization Basic dGVzdDpzZWNyZXQ=
Content-Type application/x-www-form-urlencoded

grant_type=password&username=cym/manager&password=passwordExample123


14.2.2 Response

The following is an example of a typical response:

{
  "access_token": "77cf4834-a347-4849-839b-4518823a739e",
  "token_type": "bearer",
  "expires_in": 43199,
  "scope": "general",
  "cluster_url": "https://et.dev.coresuite.com",
  "account": "testaccount",
  "account_id" : 284,
  "user": "manager",
  "user_email": "test@coresystems.ch",
  "companies": [
    {
      "id": 957,
      "name": "SBODemoCH",
      "description": "OEC Computers (Schweiz)"
    }
  ],
 }
 

14.2.3 Error Response

{
  "error": "invalid_grant",
  "error_description": "Bad credentials"
}

14.2.4 Supported Clusters

Depending on the location of the account, requests will be made to one of the following server clusters:

  • EU
  • DE
  • US
  • CN

Account information, including cluster assignment, are obtained from the Directory API.

This information is passed into requests made to the Rating API as follows:

https://{cluster}.coresystems.net/cloud-rating-service/api/v1/rating/


14.3 GET a Review of an Activity

Retrieve details of an existing customer review created for a specific activity.

14.3.1 Request

Method URL
GET https://{cluster}.coresystems.net/cloud-rating-service/api/v1/rating/review

14.3.2 Headers

Header Parameter Description Required
accountId accountId The numerical ID associated with the account. Required
companyId companyId The numerical ID associated with the company. Required

14.3.3 Query Parameters

Query Parameter Description Required
activityId The alphanumerical ID associated with the activity. Optional

14.3.4 Response

Status Response
200 OK
401 Unauthorized
403 Forbidden
404 Not found

14.3.5 Example Response

{
  "changeDateTime": "2019-04-30T10:26:40.549Z",
  "createDateTime": "2019-04-30T10:26:40.549Z",
  "emailId": 0,
  "feedbackFormURL": "string",
  "request": {
    "contactId": "string",
    "masterActivityId": "string",
    "reviewerEmail": "string",
    "serviceCallId": "string",
    "serviceReportRequest": {
      "include": true,
      "language": "en",
      "parameters": {
        "title": "Report from Technician's Activity"
      },
      "templateName": "serviceCheckout2",
      "type": "PDF"
    },
    "technicianId": "string"
  },
  "reviewerInput": {
    "feedback": "string",
    "rating": "THUMB_UP"
  },
  "status": "CREATED",
  "uuid": "string"
}

14.4 GET Multiple Reviews

Retrieve multiple review records.

Method URL
GET https://{cluster}.coresystems.net/cloud-rating-service/api/v1/rating/reviews

14.4.1 Headers

Header Parameter Description Required
accountId accountId The numerical ID associated with the account. Required
companyId companyId The numerical ID associated with the company. Required

14.4.2 URL Parameters

Query Paramter Data Type Description
offset Integer The offset to be taken according to the page count and page size.
pageNumber Integer The number of pages to be returned.
rating String Sort using the rating from the review. Available values: THUMBS_UP, THUMBS_DOWN.
sort.sorted Boolean True or false. When true, the results will be returned in ascending order.
sort.unsorted Boolean True or false. When true, the results will be unsorted.
status String Sort using the rating status. Available values: CREATED, RATED, FINISHED, EXPIRED, RATED_EXPIRED.
unpaged Boolean True or false. When true, the results will be unpaged; i.e. all results will display on one page.

14.4.3 Response

Status Response
200 OK
401 Unauthorized
403 Forbidden
404 Not found

14.4.4 Example Response

{
  "content": [
    {
      "changeDateTime": "2019-04-30T10:26:40.560Z",
      "createDateTime": "2019-04-30T10:26:40.560Z",
      "emailId": 0,
      "feedbackFormURL": "string",
      "request": {
        "contactId": "string",
        "masterActivityId": "string",
        "reviewerEmail": "string",
        "serviceCallId": "string",
        "serviceReportRequest": {
          "include": true,
          "language": "en",
          "parameters": {
            "title": "Report from Technician's Activity"
          },
          "templateName": "serviceCheckout2",
          "type": "PDF"
        },
        "technicianId": "string"
      },
      "reviewerInput": {
        "feedback": "string",
        "rating": "THUMB_UP"
      },
      "status": "CREATED",
      "uuid": "string"
    }
  ],
  "empty": true,
  "first": true,
  "last": true,
  "number": 0,
  "numberOfElements": 0,
  "pageable": {
    "offset": 0,
    "pageNumber": 0,
    "pageSize": 0,
    "paged": true,
    "sort": {
      "empty": true,
      "sorted": true,
      "unsorted": true
    },
    "unpaged": true
  },
  "size": 0,
  "sort": {
    "empty": true,
    "sorted": true,
    "unsorted": true
  },
  "totalElements": 0,
  "totalPages": 0
}

14.5 GET Review by UUID

Retrieve details of an existing customer review using uuid.

14.5.1 Request

Method URL
GET https://{cluster}.coresystems.net/cloud-rating-service/api/v1/rating/reviews/{uuid}

14.5.1 URL Parameters

Header Parameter Description Required
uuid uuid The alphanumerical ID associated with the existing review to be retrieved. Required

14.5.2 Headers

Header Parameter Description Required
accountId accountId The numerical ID associated with the account. Required
companyId companyId The numerical ID associated with the company. Required

14.5.4 Response

Status Response
200 OK
401 Unauthorized
403 Forbidden
404 Not found

14.5.5 Example Response

{
  "changeDateTime": "2019-04-30T10:26:40.581Z",
  "createDateTime": "2019-04-30T10:26:40.581Z",
  "emailId": 0,
  "feedbackFormURL": "string",
  "request": {
    "contactId": "string",
    "masterActivityId": "string",
    "reviewerEmail": "string",
    "serviceCallId": "string",
    "serviceReportRequest": {
      "include": true,
      "language": "en",
      "parameters": {
        "title": "Report from Technician's Activity"
      },
      "templateName": "serviceCheckout2",
      "type": "PDF"
    },
    "technicianId": "string"
  },
  "reviewerInput": {
    "feedback": "string",
    "rating": "THUMB_UP"
  },
  "status": "CREATED",
  "uuid": "string"
}

14.6 POST Updated Review

Update a review that has not yet been completed. This occurs when the customer has already clicked on rating icon on his / her email. The process is almost finished, but still some feedback text is needed.

14.6.1 Request

Method URL
POST https://{cluster}.coresystems.net/cloud-rating-service/api/v1/rating/reviews/{uuid}/actions/rate

14.6.2 URL Parameters

Header Parameter Description Required
uuid uuid The alphanumerical ID associated with the existing review to be updated. Required

14.6.3 Headers

Header Parameter Description Required
accountId accountId The numerical ID associated with the account. Required
companyId companyId The numerical ID associated with the company. Required

14.6.4 Body

When completing this request, the body should include a rating field with either THUMBS_UP or THUMBS_DOWN:

{  
   "contactId":"string",
   "masterActivityId":"string",
   "reviewerEmail":"string",
   "serviceCallId":"string",
   "serviceReportRequest":{  
      "include":true,
      "language":"en",
      "parameters":{  
         "title":"Report from Technician's Activity"
      },
      "templateName":"serviceCheckout2",
      "type":"PDF"
   },
   "technicianId":"string"
},
"reviewerInput":{  
   "feedback":"string",
   "rating":"THUMB_UP",
},
"status":"FINISHED",
"uuid":"string"
}

14.6.5 Response

Status Response
200 OK
401 Unauthorized
403 Forbidden
404 Not found

14.7 POST FINISHED Review

Review is finished by a customer. This completes feedback process. The same review cannot be updated again.

14.8.1 Request

Method URL
POST https://{cluster}.coresystems.net/cloud-rating-service/api/v1/rating/reviews/{uuid}/actions/finish

14.7.2 URL Parameters

Header Parameter Description Required
uuid uuid The alphanumerical ID associated with the existing review to be deleted. Required

14.7.3 Headers

Header Parameter Description Required
accountId accountId The numerical ID associated with the account. Required
companyId companyId The numerical ID associated with the company. Required

14.7.4 Body

When completing this request, the feedback field will contain the text provided by the customer:

{  
   "contactId":"string",
   "masterActivityId":"string",
   "reviewerEmail":"string",
   "serviceCallId":"string",
   "serviceReportRequest":{  
      "include":true,
      "language":"en",
      "parameters":{  
         "title":"Report from Technician's Activity"
      },
      "templateName":"serviceCheckout2",
      "type":"PDF"
   },
   "technicianId":"string"
},
"reviewerInput":{  
   "feedback":"string",
   "rating":"THUMB_UP",
},
"status":"FINISHED",
"uuid":"string"
}

14.7.4 Response

Status Response
200 OK
401 Unauthorized
403 Forbidden
404 Not found

14.8 Delete Review by UUID

Delete an existing review using uuid.

14.8.1 Request

Method URL
DELETE https://{cluster}.coresystems.net/cloud-rating-service/api/v1/rating/reviews/{uuid}

14.8.2 URL Parameters

Header Parameter Description Required
uuid uuid The alphanumerical ID associated with the existing review to be marked with FINISHED status. Required

14.8.3 Headers

Header Parameter Description Required
accountId accountId The numerical ID associated with the account. Required
companyId companyId The numerical ID associated with the company. Required

14.8.3 Response

Status Response
200 OK
204 No content
401 Unauthorized
403 Forbidden

Appendix

Models

Customer Review

Customer Review model {
    changeDateTime string($date - time)
    readOnly: true
    Timestamp when review was changed last time(e.g.its status was changed)
    createDateTime * string($date - time)
    readOnly: true
    Timestamp when review process was started
    emailId integer($int32)
    readOnly: true
    Identifier of Email stored by Messaging API(Cloud)
    feedbackFormURL * string
    Address of Customer feedback form
    request * Review request model {
        ...
    }
    reviewerInput * Customer 's feedback details{...}
    status * string
    readOnly: true
    Current status
    Enum:
        Array[5]
    uuid * string($uuid)
    readOnly: true
    Unique identifier of the review
}

Customer Feedback Details

Customer 's feedback details{
    feedback * string
    minLength: 1
    maxLength: 255
    Feedback / comment from the Customer
    
    rating * string
    Grade of the Service according to customer
    Enum:
        Array[2]
}

Review Request

Review request model {
    contactId string
    minLength: 32
    maxLength: 32
    Identifier of Contact person.
    masterActivityId * string
    minLength: 32
    maxLength: 32
    Identifier of closed master(main) Activity where Technician was responsible.
    reviewerEmail * string
    maxLength: 255
    Address where a link to review + report of Service will be sent to.Email should be compliant to W3C pattern
    serviceCallId * string
    minLength: 32
    maxLength: 32
    Identifier of ServiceCall
    for which Technician was performing his duties.
    serviceReportRequest Service Report request model {
        ...
    }
    technicianId * string
    minLength: 32
    maxLength: 32
    Identifier of Technician Person who performed the Service
}

Service Report Request

Service Report request model {
    include * boolean
    Whether to generate and include a report.
    language string
    example: en
    maxLength: 32
    Generated report language.If not specified then
    default one will be used.
    parameters {
        ...
    }
    templateName string
    example: serviceCheckout2
    maxLength: 255
    Template name to use to generate a report.If not specified then
    default one will be used.Standard templates
    type string
    example: PDF
    maxLength: 255
    Generated report type.If not specified then
    default one will be used.
}