Integrate with ServiceMax Zinc

Estimated Effort  ~ 10 minutes or less

Learning Objectives

After completing this unit, you will be able to:

  • Configure a group in Zinc to receive messages from ProntoForms
  • Send messages to Zinc using an HTTP Post Data Destination
  • Configure a Help Link to launch a conversation in Zinc

 

Getting Started with the Zinc Messaging API

Zinc connects technicians in real time with the people and information needed to confidently get the job done quickly and correctly, allowing the organization to reduce mean time to repair, boost customer satisfaction and improve employee engagement.

Using the Zinc Messaging API, in conjunction with ProntoForms HTTP POST data destination, you can send messages to Zinc following the submission of a Form. Messages you compose in ProntoForms can be delivered to a group, hotline, or directly to a user. 

Step-by-Step

Your Use Case - Post a Message to Zinc 

Here is a common use case: A group of service managers would like to be notified in Zinc whenever a Work Order has been completed. The following video provides a quick overview of the workflow to give further context to the example which follows. 

In Zinc

1. From the Zinc Admin Console, create an Official Group

2. Next, Create a Bot or a Hotline in your Official Group.

Take note of the e-mail address associated with your Bot or Hotline. The characters preceding @bots.zincit.io or @hotlines.zincit.io make up your Bot Identification Token or Integration Token. You will need this token when configuring your Data Destination in ProntoForms.

Screen_Shot_2019-09-10_at_10.08.02_AM.png

 

In ProntoForms

1. Set up your HTTP Connection - Select the appropriate FormSpace, enter the Base URL (https://api.zincit.io), and select the box for Anonymous Access.

 mceclip1.png

2. Compose your Document - Create a new Template-driven Text Document. The following example uses Handlebars to compile the message which we will send to Zinc.

          Screen_Shot_2019-09-23_at_9.00.16_PM.png

The body of the JSON to be sent to Zinc contains three sentences. First, there is a hard-coded sentence indicating that a Work Order has been completed, along with a dynamic reference to Work Order Number.

{{ answers.WorkOrderNumber.[0]}}

The second sentence includes a URL which is composed of a hard-coded reference to the ServiceMax Org where the completed work order can be viewed:

https://na136.salesforce.com/{{answers.RecordID.[0]}}

Followed by a dynamic reference to the Record ID, which is the External ID for the Work Order in ServiceMax. 

https://na136.salesforce.com/{{answers.RecordID.[0]}}

Note: In this example, the Work Order Number and Record ID has been dispatched to ProntoForms using a User-Defined Custom Action in Service Max. To reference this data dynamically, we simply use the question label for the questions in your form which will capture this data. The Work Order Number and Record ID could also be hard coded, instead. 

The entirety of the Handlebars template is provided below: 

 {
"body": "A Work Order has been completed: {{ answers.WorkOrderNumber.[0]}}. \n View Work Order in ServiceMax - https://na136.salesforce.com/{{answers.RecordID.[0]}}. \n View Service Report in ProntoForms - https://live.prontoforms.com/data/{{dataRecord.identifier}}.pdf "
}

3. Configure your Data Destination 
Configure an HTTP POST Data Destination. Under Connection Configuration, select the Connection established in Step 1 "Set up your Connection" above. For HTTP Method, select POST. In the URL Suffix, enter /hooks/v1/:id/message, where ":id" is replaced with your Bot Identification Token, or Integration Token as described above.

          mceclip3.png

4. Submit your Form
Once you have submitted your form, check Zinc to see your new message!

Screen_Shot_2019-09-23_at_9.42.32_PM.png 

 

 

Extend Your Use Case - Optionally Start a Conversation in Zinc 

Here is a common use case: While completing a form, a technician may seek help from a product or service specific Hotline as defined in Zinc. Using the Web Link help type on an Information Label question, we can launch a conversation directly from the form.  

Zinc Hotlines are powered by Bots. So when someone sends a message to a hotline they are actually sending a message to a Hotline Bot. The Hotline Bot is a participant in the conversation and when it receives a message is creates a request.

Your Web URL should be configured as follows:

https://zinc-app.com/cnv?participants=ParticipantParameter

Where the participants parameter is the token of the Hotline Bot (which can be found in the Zinc Admin UI, as described above).

Note: Using the same configuration above, you could also launch a conversation with an Official Group by referencing a Bot token, or an individual participant. Click here to learn more about Zinc Conversation Deep Links. 

          Screen_Shot_2019-09-23_at_9.21.11_PM.png

 

Simple Templates - Using DREL to compose basic messages

If you are composing a basic message which does not require conditional logic, then you may follow the simple examples below which make use of a DREL Document Template.

Example 1 Hardcode a message to be sent to an Official Group or Hotline in Zinc.  

{
  "body": "hello world."
}

Example 2 Using DREL , compose a message to an Official Group or Hotline in Zinc.

{
  "body": "%a[QuestionLabel]"
}

Example 3 Send a direct message to Zinc users. Identify recipients by email, as shown in the example below.  

{
  "recipients": ["address@example.com"],
  "body": "hello world."
}

Example 4 Optionally, use DREL to enter the recipient's email address.

{
  "recipients": ["%u[email]"],
  "body": "hello world."
}
Was this article helpful?
1 out of 1 found this helpful
Have more questions? Submit a request

Comments