Skip to main content


         This documentation site is for previous versions. Visit our new documentation site for current releases.      
 

This content has been archived and is no longer being updated.

Links may not function; however, this content may be relevant to outdated versions of the product.

Client outreach API

Updated on September 10, 2021

As an alternative method to a web self-service (WSS) portal, customers can opt for building their client self-service applications by using their own front-end technologies. The new API that is shipped with the Client outreach functionality enables these front-end applications to retrieve the Client outreach cases and fulfill them as required. The following methods are supported by the API:

  • Retrieve list of cases addressed to a given customer.
  • Retrieve all details available from a given case.
  • Retrieve the document associated with a given item in a Client outreach case.
  • Provide an answer to a given item in a case.
  • Provide a document to a given item in a case.

For more information about each of these methods, in Dev Studio, click <application name> > Channels and interfaces, select API, and then select the Application tab.

API methods

Retrieval of cases

GET /clm/clientoutreach/v1/cases/{recipientId}

Parameters

Parameters

 

Type

Required

Description

recipientId (string)

String

URL

Yes

Customer identifier of the recipient of the cases to be returned by the service.

authenticationid (string)

String

Header

Yes

Customer identifier of the customer making the service call.

filterByStatus (string)

String

URL Param

No

Filter by case status (for example, Pending-Fulfillment, Resolved-Complete).

Response codes

HTTP Code

Description

Content of response

200

Success

Data element that contains items of the PegaFS-Int-ClientOutreach-Data-ClientList class.

400

Failure

Messages element that contains a list of PegaFS-Int-ClientOutreach-Data-Message class messages.

Sample messages

Messages

Request

url

https://{serverURL}/prweb/PRRestService/CLMFS/v1/clm/clientoutreach/v1/cases/0000169171

header

authenticationId: 0000169171

Response

{

    "data": {

        "clients": [

            {

                "clientName": "clientABC",

                "clientID": "3117",

                "case": [

                    {

                        "caseStatus": "Resolved-Completed",

                        "caseID": "CO-14007",

                        "caseConsolidatedID": "3117#0000169171"

                    }

                ]

            },

            {

                "clientName": "NiceCo",

                "clientID": "180",

                "case": [

                    {

                        "caseStatus": "Resolved-Completed",

                        "caseID": "CO-27003",

                        "caseConsolidatedID": "180#0000169171"

                    },

                    {

                        "caseStatus": "Pending-Fulfillment",

                        "caseID": "CO-27004",

                        "caseConsolidatedID": "180#0000169171"

                    }

                ]

            }

        ]

    },

    "messages": []

}

Retrieval of case details

GET /clm/clientoutreach/v1/cases/{recipientId}/{caseId}

Parameters

Parameters

 

Type

Required

Description

recipientId

String

URL

Yes

Customer identifier of the recipient of the cases to be returned by the service.

caseId

String

URL

Yes

Unique identifier of the client outreach case.

authenticationid

String

Header

Yes

Customer identifier of the customer making the service call.

Response codes

HTTP Code

Description

Content of response

200

Success

Data element that contains items of the PegaFS-Int-ClientOutreach-Data- Case class.

400

Failure

Messages element that contains a list of PegaFS-Int-ClientOutreach-Data-Message class messages.

Sample messages

Messages

Request

url

https://{serverURL}/prweb/PRRestService/CLMFS/v1/clm/clientoutreach/v1/cases/0000169171/CO-27004

header

authenticationId: 0000169171

Response

{

    "data": {

        "item": [

            {

                "itemValue": "street 123, NY",

                "itemType": "Data item",

                "itemName": "Please provide full address",

                "pyGUID": "649d27b7-362f-435c-ada8-b2f7d1a18265"

            },

            {

                "itemValue": "",

                "itemType": "Document",

                "itemName": "Please provide proof of address",

                "pyGUID": "9220148d-bfc3-4886-99a0-d9b552706282"

            },

            {

                "itemValue": "",

                "itemType": "Data item",

                "itemName": "Please provide TAX ID",

                "pyGUID": "bf322441-59ff-4366-8360-8f63c071cfb5"

            }

        ],

        "recipientID": "0000169171",

        "clientDetails": {

            "clientName": "NiceCo",

            "clientID": "180"

        },

        "caseStatus": "Pending-Fulfillment",

        "caseID": "CO-27004",

        "caseConsolidatedID": "180#0000169171"

    },

    "messages": []

}

Fulfillment of data item in case

PUT /clm/clientoutreach/v1/cases/{recipientId}/{caseId}

Parameters

Parameters

 

Type

Required

Description

recipientId

String

URL

Yes

Customer identifier of the recipient of the cases to be returned by the service.

caseId

String

URL

Yes

Unique identifier of the client outreach case.

itemGUID

String

URL

Yes

Data item unique ID.

.itemValue

String

URL

Yes

Data item value.

resolveRequest

Boolean

URL

Yes

Boolean whether to resolve request.

authenticationid (string)

String

Header

Yes

Customer identifier of the customer making the service call.

Response codes

HTTP Code

Description

Content of response

200

Success

Data element that contains items of the PegaFS-Int-ClientOutreach-Data- Case class.

400

Failure

Messages element that contains a list of PegaFS-Int-ClientOutreach-Data-Message class messages.

Sample messages

Messages

Request

url

https://{serverURL}/prweb/PRRestService/CLMFS/v1/clm/clientoutreach/v1/cases/0000169171/CO-27004?itemGUID=649d27b7-362f-435c-ada8-b2f7d1a18265&itemValue=street 456, BO&resolveRequest=false

header

authenticationId: 0000169171

Response

{

    "data": {

        "item": [

            {

                "itemValue": "street 456, BO",

                "itemType": "Data item",

                "itemName": "Please provide full address",

                "pyGUID": "649d27b7-362f-435c-ada8-b2f7d1a18265"

            },

            {

                "itemValue": "",

                "itemType": "Document",

                "itemName": "Please provide proof of address",

                "pyGUID": "2345d264-dbb9-44c8-859b-27123928422c"

            },

            {

                "itemValue": "",

                "itemType": "Data item",

                "itemName": "Please provide TAX ID",

                "pyGUID": "bf322441-59ff-4366-8360-8f63c071cfb5"

            }

        ],

        "recipientID": "0000169171",

        "clientDetails": {

            "clientName": "NiceCo",

            "clientID": "180"

        },

        "caseStatus": "Pending-Fulfillment",

        "caseID": "CO-27004",

        "caseConsolidatedID": "180#0000169171"

    },

    "messages": []

}

Retrieval of document

GET /clm/clientoutreach/v1/document/{docGUID}

Parameters

Parameters

 

Type

Required

Description

docGUID

String

URL

Yes

Unique identifier for the document in the list of items of a case.

authenticationid (string)

String

Header

Yes

Customer identifier of the customer making the service call.

Response codes

HTTP Code

Description

Content of response

200

Success

Data element that contains items of the PegaFS-Int-ClientOutreach-Data-Item class with the ItemContent property filled. Property itemContent contains document coded in base64.

400

Failure

Messages element that contains a list of PegaFS-Int-ClientOutreach-Data-Message class messages.

Sample messages

Messages

Request

url

https://{serverURL}/prweb/PRRestService/CLMFS/v1/clm/clientoutreach/v1/document/2345d264-dbb9-44c8-859b-27123928422c

header

authenticationId: 0000169171

Response

{

    "data": {

        "itemValue": "proofOfAddress",

        "itemType": "Document",

        "itemName": "Please provide proof of address ",

        "pyGUID": "2345d264-dbb9-44c8-859b-27123928422c",

        "itemContent": "dGVzdA==\r\n"

    },

    "messages": []

}

Fulfillment of document item in case

POST /clm/clientoutreach/v1/document/{docGUID}

Parameters

Parameters

 

Type

Required

Description

docGUID

String

URL

Yes

Unique identifier for the document in the list of items of a case.

docValue

String

URL

Yes

Name of the document.

fileName

String

URL

Yes

File name.

resolveRequest

Boolean

URL

Yes

Boolean whether to resolve request.

authenticationid (string)

String

Header

Yes

Customer identifier of the customer making the service call.

Response codes

HTTP Code

Description

Content of response

200

Success

Data element that contains items of the PegaFS-Int-ClientOutreach-Data-Item class without the ItemContent property filled.

400

Failure

Messages element that contains a list of PegaFS-Int-ClientOutreach-Data-Message class messages.

Sample messages

Messages

Request

url

https://{serverURL}/prweb/PRRestService/CLMFS/v1/clm/clientoutreach/v1/document/2345d264-dbb9-44c8-859b-27123928422c?docValue=NewProofOfAddress &fileName=NewproofOfAddress.pdf&resolveRequest=false

header

authenticationId: 0000169171

body

dGVzdA==

Response

{

    "data": {

        "itemValue": " NewproofOfAddress ",

        "itemType": "Document",

        "itemName": "Please provide proof of address ",

        "pyGUID": "2345d264-dbb9-44c8-859b-27123928422c",

    },

    "messages": []}

Implementation

Service infrastructure

Name

Type

Details

CLMFS

Service Package

Processing mode: Stateless

Service Access Group: CLMFS_API

Requires Authentication: Yes

Authentication Type: Basic

Requires TLS/SSL for REST services in this package: Yes

Supress Show-HTML: Yes

ClientOutreachRecipientListPrepare_ext

Access Group

Application: CLMFS 8

Portals: no portals

Roles: PegaCLMFS:WorkMgr, PegaCLMFS:API (New) - Additional roles can be added as required

CLMFSAPI

Operator

Access group: CLMFS_API

Class Structure

The API is built under its own class structure. There are two main branches that contain all classes:

  • Data – Contains classes used to build the API data model.
  • Svc – Contains rules to implement the actual logic of the services.

Class

Purpose

PegaFS-Int-ClientOutreach

Container for all classes.

PegaFS-Int-ClientOutreach-Svc

Container for classes used to implement services.

PegaFS-Int-ClientOutreach-Svc-Cases

Implements service cases.

PegaFS-Int-ClientOutreach-Svc-Documents

Implements service documents.

PegaFS-Int-ClientOutreach-Data 

Container of data classes.

PegaFS-Int-ClientOutreach-Data-Message 

Represents a message (error/warning) to be returned.

PegaFS-Int-ClientOutreach-Data-Case 

Represents a client outreach case.

PegaFS-Int-ClientOutreach-Data-Client

Represents a client for client outreach case.

PegaFS-Int-ClientOutreach-Data-ClientList

Represents a list of clients for client outreach cases.

PegaFS-Int-ClientOutreach-Data-Item

Represents a client outreach item (generic).

PegaFS-Int-ClientOutreach-Data-Item-Data-Basic

Represents a client outreach item (data).

PegaFS-Int-ClientOutreach-Data-Item-Doc-Basic

Represents a client outreach item (document).

Single entry point

As there are multiple operations that are common for each method, however, one single point of entry – the SvcLauncher activity. The main entry point is responsible for:

  • Invoking proper service implementation (method)
  • Transaction management
  • Error handling
  • Logging and tracking calls

To recognize which method should be run, the SvcActivity parameter must be passed to SvcLuncher. It should contain the name of the data transform that implements the specific logic that executes the service.

Authentication

Apart from default authentication that is based on the service package configuration, the API should always ensure that the customer making the call can access the recipient that the cases are addressed to. The different services use the CheckAccessToRecipient activity, an extension point that checks that the identifier provided as the authentication ID is the same as the recipient of the case or cases targeted by the services. Customers can overwrite this rule if they have other rules that drive the visibility of cases.

Name

Type

Details

CheckAccessToRecipient

Activity

Class: PegaFS-Int-ClientOutreach-Svc

Parameters: AuthorizationId

Parameters: RecipientId

Return true if both values are the same

Response messages

Services return different messages (errors and warnings). Messages are stored in the messages property available in the response class. Service rules can add messages by using a certain code. The code is categorized by a decision table (error/warning/info) and given a description.

Name

Type

Details

SvcAddMessage

Decision Table

Class: PegaFS-Int-ClientOutreach-Svc

Parameters: Code

Parameters: Body

 

 

Using the code retrieved from a decision table: type (error/warning/info) and its description (with optional details from Body parameter). Append code and description to messages list in response

Tracking

The system provides auditing capability that can be used by both IT departments and auditors to show which calls were made through the API. The audit data resides in the database so that it can be stored and accessed in a structured way and protected from direct access. Entries in the audit tracking can be found in the PegaFS-Int-ClientOutreach-Audit class.

Class

Purpose

Service

Default value: CO

Application

Defaut value: CLMFS

Method

Method being invoked (for example SvcGetCase, SvcSaveCase, and so on)

CallerId

Authenticated ID

ExecutionTime

Time of invocation

Parameters

Parameters sent along with request

RequestBody

Payload of the request

ResponseBody

Payload of the response

ResponseCode

HTTP response code

ResponseTime

Time in minutes that it took to process the request

The audit capabilities can be enabled or disabled by changing the ClientOutreachTrackingEnable property in D_AppExtension.

Tags

Pega Client Lifecycle Management for Financial Services 8.3 - 8.4 Financial Services

Have a question? Get answers now.

Visit the Support Center to ask questions, engage in discussions, share ideas, and help others.

Visit the Support Center

Did you find this content helpful?

Yes
No

Want to help us improve this content?
Suggest an edit

We'd prefer it if you saw us at our best.

Pega.com is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us