Introduction

The Juniper Support Service Request APIs are a well-defined set of REST APIs that enable Clients (Juniper Customers and Partners) to integrate their Support CRM/ticketing systems with Juniper’s Support CRM system. As part of this B2B integration Clients can:

  • automatically create a Service Request (SR) in Juniper’s Support CRM system based on a case/ticket/incident in their system,
  • manage the SR lifecycle via this API channel for example to; update the case, attach files, escalate the case, request case closure,
  • receive asynchronous updates to the SR made by Juniper Support engineers and/or other channel updates without the need to poll.

Clients integrating their support CRM/ticketing system with Juniper via this channel avoid duplication of the data. The integration simplifies the process and reduces effort as users only need to enter data once in their CRM/ticketing system.

The Case API is available to customers who have an active Juniper Care or partner equivalent support contract. The Support Service Request APIs Overview video provides an overview of the API highlighting key aspects and details.

Note: Juniper uses Case and Service Request interchangeably.

Terminology

Term Description
Account ID Juniper Account identifier. Registered users can be associated to one or more Accounts.
API Application Programming Interface
AppID API Key provided by Juniper. Required to be provided in each API request.
Client Customer or Partner integrating their Support CRM system with Juniper’s Support CRM system using this API channel.
CRM Customer Relationship Management system
Host Juniper’s CRM system and AWS S3 storage space.
IdP Identity provider
OIDC OpenID Connect
REST API API based on Representational State Transfer using HTTP/HTTPS.
Service Request (SR) Support case in Juniper’s Support system. Case and Service Request are interchangeable in this document.
UserID The registered UserID (provided as part of onboarding) the Client uses in request API calls.

High-level API Model

The following illustrates a high-level view of the Case API framework. This framework allows you to integrate your ticketing system with Juniper’s Support CRM system. This a B2B integration. Two authentication mechanisms are supported. An authentication phase followed by a request/response is the typical flow.

The architecture supports a push notification model. Clients receive asynchronous updates immediately on case updates. Push Notification is also called the Publish/Subscribe model. A polling model is not supported. See Push Notifications.

There are 10 Case APIs and two push notifications. See Case API Descriptions for an overview.

The APIs are RESTful, the data format is JSON and the transport is HTTPS (TLS 1.2+).

Create Case Model

The following shows the API interactions for the createSR API request.

Update Case Model

The following shows the API interactions for the update API requests (updateSR, escalateSR, closeSR, updateRMA).

Query Case Model

The following shows the API interactions for the query API requests (querySR, queryNote, queryRMA).

Rate Limit

Rate Limit is defined as the maximum number of Case API requests that can be submitted per hour. Each client will be permitted a maximum of 300 requests/hour. Upon receipt of a request the rate of requests is calculated and if it exceeds 300 requests/hour the request will not be processed and a rate limit exceeded error is sent.

Case API Descriptions

ID API Description
1 createSR

Create a Service Request and associate it with the customerCaseNumber from the request.

Note: createSR response will NOT contain the Juniper serviceRequestNumber. The publishSR sent asynchronously to the client endpoint after the creation of the service request includes the serviceRequestNumber along with the customerCaseNumber sent in the request. The customerCaseNumber must be unique in each createSR request.

2 updateSR Update the SR with a Note, modify the Synopsis, Problem Description provided during createSR, change priority, change the followup method, set/modify routerName and overwrite cc email with a new cc list.
3 escalateSR Escalate an SR specifying a reason code and including an escalation note.
4 closeSR Provide confirmation to Juniper Service Request Owner to close the SR.
5 getFileUploadToken Attaching a file to an SR is a three-step process. First step is to obtain a stsToken from Juniper using this API. The response contains the required token information for the Client to use with AWS S3 SDK to upload files to Juniper's AWS S3 storage (see Amazon's Using The MP Java API documentation.).
6 attachFile Pass information about the uploaded files. After successfully uploading the file or files to Juniper's AWS S3 storage, call this API to link the file to the SR for access by Juniper's agents.
7 querySR Request SR details using the CCN and SRID. The response contains SR details, including lists of notes, attachments, RMAs, and linked content, plus the full content of the latest 5 notes.
8 queryNote

Request the contents of a note in an SR by SRID and NoteID. The response is note contents for that NoteID in the specified SR.

Note: Bulk extraction of all notes is NOT supported.

9 queryRMA Request RMA details using the CCN, SRID, and RMA number. SRs can have multiple RMAs. You must call queryRMA for each RMA in the SR. The response contains RMA details.
10 updateRMA Update the carrier and waybill number of RMA defective item when you ship the defective item back to Juniper.
11 publishSR Based on certain SR events, Juniper publishes SR details, including list of notes, attachments, RMAs and linked content, plus the full content of the latest 5 notes. The payload is the same as sent in querySR response.
12 publishLOV Publishes a pre-defined list of values (LOV) for various keys for Client Support CRM system to use for composing API requests.

publishSR Process (Push Notifications)

Clients must provide a secure endpoint for Juniper to post messages. You can receive real-time notifications of changes to your SRs, so you don’t have to track your open SRs and frequently do a querySR. This helps avoid reaching your rate limit. This is our publish/subscribe model, which is same as a push notification model.

On SR changes, push notifications are immediately sent to your secure endpoint which contain a JSON payload of the SR (with all SR details). You can update the corresponding ticket on your CRM support system right from the notification.

On a periodic basis Juniper will also publish the pre-defined list of values (LOV) (publishLOV) for various keys for Client application to use for composing API requests.

publishSRs (SR push notifications) and publishLOV are sent over HTTPS to your secure endpoint. Juniper can authenticate with your secure endpoint using certificate-based authentication or any standard authentication mechanisms, except username and password.

The architecture supports clients with one crm system and one endpoint or mulitple crm systems and one end point or multiple crm systems with multiple end points. The payload always includes the Customer Source Identifier, Customer Case Number, and SR details.

PublishSR illustration - Client with One CRM system and One Secure Endpoint

Example publishSR Workflow - Client with One CRM System and One Secure Endpoint

PublishSR illustration - Client with Multiple CRM system and One Secure Endpoint

Example publishSR Workflow - Client with Multiple CRMs and One Secure Endpoint

PublishSR illustration - Client with Multiple CRM system and Multiple Secure Endpoints

Example publishSR Workflow - Client with Multiple CRMs and Multiple Secure Endpoints

Supported API Authentication Mechanisms

Clients can choose from two authentication mechanisms for connecting to Juniper: OIDC and Certificate based. All services are RESTful and invoked over HTTPS.

OIDC (OpenID Connect) Authentication Mechanism

OIDC is the preferred authentication mechanism for verifying identity with an internal authorization server or identity provider (IdP) to obtain basic profile information (Access and ID token) in an interoperable and RESTful manner. OpenID Connect (OIDC) specifies a RESTful HTTP API, using JSON as the data format. The ID token issued by IDP must be passed in the Authorization header when invoking the APIs. There is no need for separate credentials.

This shows the the high-level components involved in the OIDC authentication mechanism.

OIDC Authentication Components

This diagram shows the ODIC authentication mechanism workflow.

OIDC Authenticaiton Workflow

Certificate-based Authentication Mechanism

With client certificate-based authentication, the user presents a certificate along with a connection request to the Juniper API gateway. The gateway can use either a shared or unique client certificate to validate that the user or endpoint belongs to the requesting organization.

This shows the the high-level components involved in the Certificate-based authentication mechanism.

Certificate-based Authentication Components

This diagram shows the Certificate-based authentication mechanism workflow.

Certificate-based Authentication Workflow

Authentication and Authorization Aspects on API Requests

The request follows these authentication steps:

  1. Trusted Channel: Received with valid encrypted signature over HTTPS (TLS1.2+).
  2. Rate Control: The Client must be within the rate limits.

The request follows these authorization steps:

  1. API Key (appId): is a valid API Key in the Request header as established during the onboarding process.
  2. User Authentication (userId): userId is a registered user established during the onboarding process.
  3. Account (accountId): is a valid account identifier as established during the onboarding process.
  4. Contact Email (contactEmail): is a valid registered user identifier associated with the account.
    • On createSR this user becomes the SR Reporter.
    • On updateSR this user is recorded as the originator of the update.
  5. Service Request (serviceRequestNumber): is associated to the account.

Attaching Files to an SR

Through the API channel, you can upload files to Juniper’s AWS S3 storage space using a three-step process:

  1. Request a token (getfileUploadToken). Response contains stsToken information.
  2. Use the stsToken and any of the AWS S3 SDKs to upload the file to Juniper’s AWS S3 storage area. You can upload mulitple files using one stsToken. Note: The S3 call must include the required metadata.
  3. After a successful file(s) upload to AWS S3, call the attachFile API and provide the file details (filename and AWS filename and document path). A link to the file is created in the SR so that JTAC engineers can view the file(s) and the file(s) is also accessible via other channels, such as the Casemanager and MyJuniper portals.



Attaching Files Workflow
Note: All files reside on Juniper's AWS S3 storage area.

AWS S3 SDK References

API Versioning and Juniper Endpoints

Each Case API maintains a version. Juniper supports the current and previous versions of the APIs. When it is not possible to maintain a version, Juniper will notify Clients.

All APIs are protected. After the onboarding process, Juniper will send you the API URLs.

Click here for a list of all Juniper Case APIs.

Interested? What's Next?

If you are interested in the Juniper Case API model and capability for a B2B integration with the Juniper Support CRM system please review the Onboarding Process to get started. It is simple! Complete this Client Connection form and send it to your Juniper Account Manager or Service Business Manager.