So Rest API Tech Notes

Tech Note Template

REST APIs

Tech Note

PPSS Sales OptimizerREST APIsApplies to versions: 3.25Date :

Introduction3Account Type3Account Type REST APIs3Creating an Account Type3Retrieving Account Types4Updating an Account Type6Deleting an Account Type6Retrieving Opportunity Types6Account Type Field Definition7Retrieve Account Type field definitions7Opportunity Type8Opportunity Type REST APIs8Creating an Opportunity Type9Retrieving Opportunity Types9Updating an Opportunity Type10Deleting an Opportunity Type11Opportunity Type Field Definition11Retrieve Opportunity Type field definitions11Account12Account REST APIs12Creating an Account13Retrieving Account14Updating an Account16Deleting an Account Type17Account Field17Account Field REST APIs17Retrieving Account Field Values18Updating an Account field value19Opportunity19Opportunity REST APIs19Creating an Opportunity20Retrieving Opportunity21Updating an Opportunity22Deleting an Opportunity22Opportunity Alternative23Opportunity Alternative REST APIs23Creating an Opportunity Alternative23Retrieving Opportunity Alternative24Updating an Opportunity Alternative25Deleting an Alternative25Opportunity Alternative Fields26Opportunity Alternative Field REST APIs26Retrieving Opportunity Alternative Field Values26Updating an Opportunity Alternative field value28Opportunity Alternative Items28Opportunity Alternative Item REST APIs28Retrieving Opportunity Alternative Item29Updating an Opportunity Alternative Item31Deleting an Opportunity Alternative Item32Opportunity Alternative Transition33Opportunity Alternative Transition REST APIs33Taking transition on an Alternative33Agreement33Agreement REST APIs33Retrieving an Agreement33Retrieving all Attribute Values34Retrieving all Pricing Decisions34Error Handling for REST APIs35Introduction3Account Type3Account Type REST APIs3Creating an Account Type3Retrieving Account Types4Updating an Account Type6Deleting an Account Type6Account Type Field Definition6Retrieve Account Type field definitions7Opportunity Type7Opportunity Type REST APIs7Creating an Opportunity Type8Retrieving Opportunity Types8Updating an Opportunity Type9Deleting an Opportunity Type10Opportunity Type Field Definition10Retrieve Opportunity Type field definitions10Account11Account REST APIs11Creating an Account12Retrieving Account13Updating an Account15Deleting an Account Type16Account Field16Account Field REST APIs16Retrieving Account Field Values17Updating an Account field value18Opportunity18Opportunity REST APIs18Creating an Opportunity19Retrieving Opportunity20Updating an Opportunity21Deleting an Opportunity21Opportunity Alternative22Opportunity Alternative REST APIs22Creating an Opportunity Alternative22Retrieving Opportunity Alternative23Updating an Opportunity Alternative24Deleting an Alternative24Opportunity Alternative Fields25Opportunity Alternative Field REST APIs25Retrieving Opportunity Alternative Field Values25Updating an Opportunity Alternative field value27Opportunity Alternative Items27Opportunity Alternative Item REST APIs27Retrieving Opportunity Alternative Item28Updating an Opportunity Alternative Item30Deleting an Opportunity Alternative Item31Opportunity Alternative Transition32Opportunity Alternative Transition REST APIs32Taking transition on an Alternative32Agreement32Agreement REST APIs32Retrieving an Agreement32Retrieving all Attribute Values33Retrieving all Pricing Decisions33Error Handling for REST APIs34

IntroductionDocuments summarizes the REST APIs that will be provided in PPSS Sales Optimizer 3.25. The REST APIs will be able to support a workflow where a quote can be generated and published with appropriate pricing and terms and conditions. Following section of the document briefly describes different entities in Sales Optimizer followed by REST APIs support for those entities.Account TypeConfiguration created by system configuration person that drives the definition of the account. Dimensions used to define an account, dimensional restrictions, fields, will all be driven by the account type.

Account Type REST APIs

POST /salesoptimizer/accounttype: Adds an account type GET /salesoptimizer/accounttype: Retrieves the account type collection GET /salesoptimizer/accounttype/{accountTypeId}: Retrieves an account type by Id PUT /salesoptimizer/accounttype/{accountTypeId}: Updates the given account type DELETE /salesoptimizer/accounttype/{accountTypeId}: Deletes an account type by Id

Account Type PropertiesFieldI/ODescription

Id(read only)The id of the account type is auto generated by system.

KeyDimensionsrequiredThe KeyDimensions is a set of dimension name and level pairs. This defines account type definition.

NamerequiredThe name for account type.

NoteoptionalThe note for an account type.

Creating an Account TypeA new account type can be created by doing a POST on following URI: /salesoptimizer/accounttype/This operation will create a new account type in the system.Method: POSTURI: /salesoptimizer/accounttypeRequest Header:Content-Type: application/json

Body:{ "Name": "National Account Type", "Note": "", "KeyDimensions": [ { "DimensionName": "CUSTOMER", "DimensionLevel": "CUSTOMER_ID" } ]}

Response:Response: 201

Retrieving Account TypesAccount types can be retrieved by doing a GET on following URI:/salesoptimizer/accounttype/This operation will return the collection of account type.Method: GETURI: /salesoptimizer/accounttypeRequest Header:Content-Type: application/json

Response:{ "AccountTypes": [ { "Name": "National Account Type", "Note": "", "KeyDimensions": [ { "DimensionName": "CUSTOMER", "DimensionLevel": "CUSTOMER_ID" } ], "Id": 1111 }, { "Name": "Regional Account Type", "Note": "", "KeyDimensions": [ { "DimensionName": "CUSTOMER", "DimensionLevel": "CUSTOMER_ID" } ], "Id": 1112 } ]}

Doing a GET on following URI will return account type with given account type id:/salesoptimizer/accounttype/{accountTypeId}Where {accountTypeId} is the Id of the account type that needs to be retrieved.Method: GETURI: /salesoptimizer/accounttype/{accountTypeId}Request Header:Content-Type: application/json

Response:{ "Name": "Regional Account Type", "Note": "", "KeyDimensions": [ { "DimensionName": "CUSTOMER", "DimensionLevel": "CUSTOMER_ID" } ], "Id": 1112}

Updating an Account TypeAn account type can be updated by doing a PUT on following URI: /salesoptimizer/accounttype/{accountTypeId}This operation will update the given account type, where {accountTypeId} is the id of the account type.Method: PUTURI: /salesoptimizer/accounttype/{accountTypeId}Request Header:Content-Type: application/json

Body:{ "Name": "National Account Types", "Note": "Updated Notes", "KeyDimensions": [ { "DimensionName": "CUSTOMER", "DimensionLevel": "CUSTOMER_ID" } ]}


Deleting an Account TypeAn account type can be deleted by doing a DELETE on following URI:/salesoptimizer/accounttype/{accountTypeId}Where {accountTypeId} is the id of account type that needs to be deleted.Method: DELETEURI: /salesoptimizer/accounttype/{accountTypeId}Request Header:Accept: application/json


Retrieving Opportunity TypesAll the opportunity types for a specified account type can be retrieve with the following URI:/salesoptimizer/accounttype/{accountTypeId}/opportunitytypeWhere {accountTypeId} is the id of account type that holds all the opportunity types to retrieve.Method: GETURI: /salesoptimizer/accounttype/{accountTypeId}/opportunitytypeRequest Header:Accept: application/json

Response:{ "OpportunityTypes": [ { "AccountTypeId": 504, "Name": "Customer Bid Pricing", "Note": "The workflow for customer bid pricing.", "Id": 6001 }, { "AccountTypeId": 504, "Name": "Contract Workflow", "Note": "Customer contract workflow", "Id": 55015 } ]}

Account Type Field DefinitionAccount type field are definition of the attributes of an account. Account type field can be text , number, date or a dimension. For e.g Addresses, Last Years Revenue, Start Date, Customer Segment respectively. Retrieve Account Type field definitionsAn account type field definitions can be retrieved by doing a GET on following URI:/salesoptimizer/accounttype/{accountTypeId}/fieldWhere {accountTypeId} is the id of an account type for which field definitions needs to be retrieved.Method: GETURI: /salesoptimizer/accounttype/{accountTypeId}/fieldRequest Header:Accept: application/json

Response:{ "FieldDefinitions": [ { "Name": "Address", "Id": 1222, "Label": "Company Address", "Editable" : true, "Required" : false }, { "Name": "Phone Number", "Id": 1223, "Label": "Contact Number", "Editable" : true, "Required": false } ]}


Opportunity TypeConfiguration created by system configuration person that drives the definition of the opportunity. Opportunity Type REST APIs

GET /salesoptimizer/accounttype/{accounttypeId}/opportunitytype: Retrieves the opportunity type collection under an account type GET /salesoptimizer/opportunitytype/{opportunityTypeId}: Retrieves an opportunity type by Id POST /salesoptimizer/opportunitytype: Adds an opportunity type PUT /salesoptimizer/opportunitytype/{opportunityTypeId}: Updates the given opportunity type DELETE /salesoptimizer/opportunitytype/{opportunityTypeId}: Deletes an opportunity type by Id

Opportunity Type PropertiesFieldI/ODescription

AccountTypeIdrequiredThe Id of the account type for which opportunity type is defined.

Idread onlyThe id of the opportunity type is auto generated by system.

NamerequiredThe name of opportunity type.

NoteoptionalThe note for an opportunity type.

Creating an Opportunity TypeA new opportunity type can be created by doing a POST on following URI: /salesoptimizer/opportunitytype/This operation will create a new opportunity type in the system.Method: POSTURI: /salesoptimizer/opportunitytypeRequest Header:Content-Type: application/json

Body:{ "Name": "Price Change Request ", AccountTypeId: 1111, "Note": ""}


Retrieving Opportunity TypesOpportunity types of an account type can be retrieved by doing a GET on following URI:/salesoptimizer/accounttype/{accountTypeId}/opportunitytypeThis operation will return the collection of opportunity type for given account type, where {accountTypeId} is the id of the account type for which opportunity needs to be retrieved. Method: GETURI: /salesoptimizer/accounttype/{accountTypeId}/opportunitytypeRequest Header:Content-Type: application/json

Response:{ "OpportunityTypes": [ { "Name": "Price Change Request", "Note": "", AccountTypeID: 1111, "Id": 2222 }, { "Name": "Bid Response", "Note": "", AccountTypeID: 1111, "Id": 2223 } ]}

Doing a GET on following URI will return an opportunity type by id:/salesoptimizer/opportunitytype/{opportunityTypeId}Where {opportunityTypeId} is the Id of the opportunity type that needs to be retrieved.Method: GETURI: /salesoptimizer/opportunitytype/{opportunityTypeId}Request Header:Content-Type: application/json

Response:{ "Name": "Price Change Request ", "Note": "", AccountTypeId: 1111, "Id": 2222}

Updating an Opportunity TypeAn opportunity type can be updated by doing a PUT on following URI: /salesoptimizer/opportunitytype/{opportunityTypeId}This operation will update the given opportunity type. Where {opportunityTypeId} is the id of the opportunity type which needs to be updated.Method: PUTURI: /salesoptimizer/opportunitytype/{opportunitytypeId}Request Header:Content-Type: application/json

Body:{ "Name": "Price Change Request ", "Note": "Updated Notes", "AccountTypeId": 1111, "Id : 2222}


Deleting an Opportunity TypeAn opportunity type can be deleted by doing a DELETE on following URI:/salesoptimizer/opportunitytype/{opportunityTypeId}Where {opportunityTypeId} is the id of opportunity type that needs to be deleted.Method: DELETEURI: /salesoptimizer/opportunitytype/{opportunityTypeId}Request Header:Content-Type: application/json


Opportunity Type Field DefinitionOpportunity type field are definition of the attributes of an opportunity. Opportunity field can be a text, number, date or a dimension. For e.g Contact Person, Total Revenue, Start Date, Location respectively. Retrieve Opportunity Type field definitionsAn opportunity type field definitions can be retrieved by doing a GET on following URI:/salesoptimizer/opportunitytype/{opportunitytypeId}/fieldWhere {opportunitytypeId} is the id of opportunity type for which field definitions needs to be retrieved.Method: GETURI: /salesoptimizer/opportunitytype/{opportunitytypeId}/fieldRequest Header:Content-Type: application/json

Response:{ "Fields" [ { "Name": "Effective Start Date", "Id": 2111, "Label": "Start Date", "Editable" : true, "Required" : true }, { "Name": "Effective End Date ", "Id": 2112, "Label": "End Date", "Editable" : true, "Required": true }, { "Name": "Contact Person", "Id": 2113, "Editable" : true, "Required": true }, { "Name": "Total Revenue", "Id": 2114, "Editable" : true, "Required": true } ]}

AccountThe organizational entity that the sales representative manages and sets prices on. In some PPSS applications this may be a particular customer, but it may be defined by combinations of dimensional values as specified in the account type key dimensions. Account REST APIs

GET /salesoptimizer/accounttype/{accountTypeId}/account: Retrieves all account for given account type GET /salesoptimizer/account?{param}: Retrieves an account for given parameters POST /salesoptimizer/account: Adds an account to the system PUT /salesoptimizer/account/{accountId}: Updates the given account DELETE /salesoptimizer/account/{accountd}: Deletes an account by Id

Account PropertiesFieldI/ODescription

AccountNumberRequiredAn account number which can uniquely identify the account in the system. This can be an alphanumeric string.

AccountTypeIdRequiredThe id of the account type to which this account belongs to.

Idread onlyThe id of the account auto generated by system.

KeyDimensionsRequiredThe KeyDimensions is a set of value for dimension name and level pairs.

NameRequiredThe name for account.

NoteoptionalThe note for an account.

Creating an AccountA new account can be created by doing a POST on following URI: /salesoptimizer/account/This operation will create a new account in the system.Method: POSTURI: /salesoptimizer/accountRequest Header:Content-Type: application/json

Body:{ "AccountTypeId": 1111, "Name": "Memorial Hospital", "AccountNumber": "MH34234438", "KeyDimensions": [ { "DimensionRole": "CUSTOMER", "DimensionLevel": "CUSTOMER_ID", "DimensionValue": "3439332" } ], "AccountNote": "Account for memorial hospital.",}


Retrieving Account Accounts under an account type can be retrieved by doing a GET on following URI:/salesoptimizer/accounttype/{accountTypeId}/accountThis operation will return the collection of accounts under an account type.Method: GETURI: /salesoptimizer/accounttype/{accountTypeId}/accountRequest Header:Content-Type: application/json

Response:{ "Accounts": [ { "AccountTypeId": 1111, "Name": " Memorial Hospital ", "AccountNumber": " MH34234438", "KeyDimensions": [ { "DimensionRole": "CUSTOMER", "DimensionLevel": "CUSTOMER_ID", "DimensionValue": "3439332" } ], "AccountNote": " Account for memorial hospital.", "Id": 3331 }, { "AccountTypeId": 1111, "Name": "Sam Houston Hospital ", "AccountNumber": "SHH3584833", "KeyDimensions": [ { "DimensionRole": "CUSTOMER", "DimensionLevel": "CUSTOMER_ID", "DimensionValue": "23453432" } ], "Id": 3332 } ]}

Doing a get on following URI will return an account with given key param:/salesoptimizer/account/?{keyParam}Where {keyParam} can uniquely identify an account in the system. It could be: number={AccountNumber} name={AccountName}&accountTypeName={AccountTypeName} name={AccountName}&accountTypeId={AccountTypeId}Method: GETURI: /salesoptimizer/account?{keyParams}e.g: /salesoptimizer/account?number=MH34234438Request Header:Content-Type: application/json

Response:{ "AccountTypeId": 1111, "Name": " Memorial Hospital ", "AccountNumber": " MH34234438", "KeyDimensions": [ { "DimensionRole": "CUSTOMER", "DimensionLevel": "CUSTOMER_ID", "DimensionValue": "3439332" } ], "AccountNote": " Account for memorial hospital.", "Id": 3331}

Doing a GET on following URI will return accounts matching search criteria:/salesoptimizer/account?{searchParam}Where {searchParam} is the matching criteria for finding an account. It could be: find={Partial name of an account (case insensitive)} find={Partial number of an account (case insensitive)}Method: GETURI: /salesoptimizer/account?{searchParams}e.g: /salesoptimizer/account?find=hospitalRequest Header:Content-Type: application/json

Response:{ "Accounts": [ { "AccountTypeId": 1111, "Name": " Memorial Hospital ", "AccountNumber": " MH34234438", "KeyDimensions": [ { "DimensionRole": "CUSTOMER", "DimensionLevel": "CUSTOMER_ID", "DimensionValue": "3439332" } ], "AccountNote": " Account for memorial hospital.", "Id": 3331 }, { "AccountTypeId": 1111, "Name": "Sam Houston Hospital ", "AccountNumber": "SHH3584833", "KeyDimensions": [ { "DimensionRole": "CUSTOMER", "DimensionLevel": "CUSTOMER_ID", "DimensionValue": "23453432" } ], "Id": 3332 } ]}

Updating an AccountAn account can be created by doing a PUT on following URI: /salesoptimizer/account/{accountId}This operation will update the given account. Where accountId is the id of the account that needs to be updated.Method: PUTURI: /salesoptimizer/account/{accountId}Request Header:Content-Type: application/json

Body:{ "AccountTypeId": 1111, "Name": " Memorial Hospital ", "AccountNumber": " MH34234438", "KeyDimensions": [ { "DimensionRole": "CUSTOMER", "DimensionLevel": "CUSTOMER_ID", "DimensionValue": "3439332" } ], "AccountNote": "Account for memorial hospital.", "Id": 3331}


Deleting an Account TypeAn account can be deleted by doing a DELETE on following URI:/salesoptimizer/account/{accountId}Where accountId is the id of account that needs to be deleted.Method: DELETEURI: /salesoptimizer/account/{accountId}Request Header:Content-Type: application/json

Response:Status Code: 204

Account FieldAccount fields are the attributes of an account. Account field can be a text, number, date or a dimension. Field definitions are defined in an account type and accounts can have their own values for those fields.

Account Field REST APIs GET /salesoptimizer/account/{accountId}/field: Retrieves the field values for all account fields GET /salesoptimizer/account/{accountId}/field/{fieldld}: Retrieves the field value for given account field PUT /salesoptimizer/account/{accountId}/field/{fieldId}: Updates the given account field value

Account Field PropertiesFieldI/ODescription

NameRequiredread-onlyThe name for account field.

FieldIdRequiredread-onlyThe FieldId is the id of the field definition defined in an account type for this account.

ValueoptionalRequiredThe value of an account field. Value should be numeric for a number field. For a date field value should be in format yyyymmdd. Value for a dimension field should be a valid dimension value in PPSS. Value of a text field can be a string, null or an empty string.

Retrieving Account Field ValuesAccount field values can be retrieved by doing a get following URI: /salesoptimizer/account/{accountId}/field/Where {accountId} the id of the account for which all field needs to be retrieved.Method: GETURI: /salesoptimizer/account/{accountId}/field/Request Header:Content-Type: application/json

Response:{ "Fields": [ { "Name": "Address", "FieldId": 1222, "Value": "12000 Richmond Ave, Houston TX, 77082" }, { "Name": "Phone Number", "FieldId": 1223, "Value": "713-713-1111" } ]}

An individual account field value can be retrieved by doing a GET on following URI:/salesoptimizer/account/{accountId}/field/{fieldId}Where {fieldId} is the id of the field and {accountId} is the id of the account for which field value needs to be retrieved.Method: GETURI: / salesoptimizer/account/{accountId}/field/{fieldId}Request Header:Content-Type: application/json

Response:{ "Name": "Address", "FieldId": 1222, "Value": "12000 Richmond Ave, Houston TX, 77082"}

Updating an Account field valueAn account field value can be updated by doing a PUT on following URI: /salesoptimizer/account/{accountId}/field/{fieldId}Where {fieldId} is the id of the field whose value needs to be updated and {accountId} is the id of the account to which field belongs.Method: PUTURI: / salesoptimizer/account/{accountId}/field/{fieldId}Request Header:Content-Type: application/json

Body:{ "Name": "Phone Number", "FieldId": 1223, "Value": "281-281-2222"}


OpportunityOpportunity is a vehicle to change pricing within an account. A sales rep can create an opportunity and use it to negotiate pricing with a customer. Opportunity REST APIs GET /salesoptimizer/account/{accountId}/opportunity: Retrieves all opportunities within an account GET /salesoptimizer/opportunity/{opportunityId}: Retrieves an opportunity by Id POST / salesoptimizer/opportunity: Adds an opportunity to the system PUT / salesoptimizer/opportunity{opportunityId}: Updates the given opportunity DELETE / salesoptimizer/opportunity{opportunityId}: Deletes an opportunity by Id

Opportunity PropertiesFieldI/ODescription

AccountIdrequiredThe note for an account type.

BidResponsePreferenceoptionalThe BidResponsePreference is to decide the preference for doing bid matching.

Idread onlyThe id of the opportunity auto generated by system.

NamerequiredThe name of the opportunity.

NoteoptionalThe note of an opportunity.

OpportunityTypeIdrequiredThe id of the opportunity type which defines this opportunity.

StageNameread onlyThe name of the stage in which opportunity is currently in its lifecycle.

Creating an OpportunityA new opportunity can be created by doing a POST on following URI: /salesoptimizer/opportunityThis operation will create a new opportunity in the system.Method: POSTURI: / salesoptimizer/opportunityRequest Header:Content-Type: application/json

Body:{ "OpportunityTypeId": 2222, "Name: "1st Quarter Opportunity, "AccountId": 3331, "Note": "opportunity notes",}


Retrieving OpportunityOpportunities can be retrieved by doing a GET on following URI:/salesoptimizer/account/{accountId}/opportunityThis operation will return all the opportunities for given account. Where {accountId} is the id of the account for which opportunities needs to be retrieved.Method: GETURI: /salesoptimizer/account/{accountId}/opportunityRequest Header:Content-Type: application/json

Response:{ "Opportunities": [ { "OpportunityTypeId": 2222, "Name": "1st Quarter Opportunity, "AccountId": 3331, "StageName": "Created", "BidResponsePreference": 0, "Note": "opportunity notes", "Id": 4441 }, { "OpportunityTypeId": 2222, "Name": "2nd Quarter Opportunity, "AccountId": 3331, "StageName": "Created", "BidResponsePreference": 0, "Note": "opportunity notes", "Id": 4442 } ]}

Response:Status Code: 200 OK

Doing a get on following URI will return an opportunity by id:/salesoptimizer/opportunity/{opportunityId}Where {opportunityId} is the Id of the opportunity that needs to be retrieved.Method: GETURI: /salesoptimizer/opportunity/{opportunityId}Request Header:Content-Type: application/json

Response:{ "OpportunityTypeId": 2222, "Name": "1st Quarter Opportunity, "AccountId": 3331, "StageName": "Created", "BidResponsePreference": 0, "Id": 4441}

Response:Status Code: 200 OK

Updating an OpportunityAn opportunity can be updated by doing a put on following URI: /salesoptimizer/opportunity/{opportunityId}Where {opportunityId} is the id of the opportunity that needs to be updated.Method: PUTURI: /salesoptimizer/opportunity/{opportunityId}Request Header:Content-Type: application/json

Body:{ "OpportunityTypeId": 2222, "Name": "1st Quarter Opportunity, "Note": 3331, "Id": 4441}


Deleting an OpportunityAn opportunity can be deleted by doing a DELETE on following URI:/salesoptimizer/opportunity/{opportunityId}Where {opportunityId} is the id of opportunity that needs to be deleted.Method: DELETEURI: /salesoptimizer/opportunity/{opportunityId}Request Header:Content-Type: application/json


Opportunity AlternativeAn opportunity alternative is one potential version of pricing for a particular opportunity. Multiple alternatives for an opportunity may be created to analyze the profitability by doing applying different pricing. Opportunity Alternative REST APIs GET /salesoptimizer/opportunity/{opportunityId}/alternative: Retrieves all alternatives within an opportunity GET /salesoptimizer/alternative/{alternativeId}: Retrieves an alternative by Id POST /salesoptimizer/opportunity/{opportunityId}/alternative: Adds an alternative to the opportunity PUT /salesoptimizer/alternative/{alternativeId}: Updates the given alternative DELETE /salesoptimizer/alternative/{alternativeId}: Deletes an alternative by Id

Opportunity Alternative PropertiesFieldI/ODescription

ActiveoptionalThe flag which indicates if alternative is active or not.

Idread onlyThe id of the opportunity auto generated by system.

NamerequiredThe name of an alternative.

OpportunityIdrequiredThe Id of the opportunity to which this alternative belongs to.

Creating an Opportunity AlternativeA new alternative can be created by doing a POST on following URI: /salesoptimizer/opportunity/{opportunityId}/alternativeWhere {opportunityId} is the id of the opportunity to which alternative needs to be added.Method: POSTURI: /salesoptimizer/opportunity/{opportunityId}/alternativeRequest Header:Content-Type: application/json

Body:{ "OpportunityId": 4441, "Name": "Default"}


Retrieving Opportunity AlternativeAn opportunity alternatives can be retrieved by doing a GET on following URI:/salesoptimizer/opportunity/{opportunityId}/alternativeWhere {opportunityId} is the id of the opportunity for which all alternatives needs to be retrieved.Method: GETURI: /salesoptimizer/opportunity/{opportunityId}/alternativeRequest Header:Content-Type: application/json

Response:{ "Alternatives": [ { "OpportunityId": 4441, "Name": "Default", "Active": true, "Id": 5551 }, { "OpportunityId": 4441, "Name": "Stretch Discount", "Active": true, "Id": 5552 } ]}

Doing a get on following URI will return an alternative by given id:/salesoptimizer/alternative/{alternativeId}Where {alternativeId} is the Id of the alternative that needs to be retrieved.Method: GETURI: /salesoptimizer/alternative/{alternativeId}Request Header:Content-Type: application/json

Response:{ "OpportunityId": 4441, "Name": "Default", "Active": true, "Id": 5551}

Updating an Opportunity AlternativeAn opportunity alternative can be updated by doing a PUT on following URI:/salesoptimizer/alternative/{alternativeId}Where {alternativeId} is the id of the alternative which needs to be updated.Method: PUTURI: /salesoptimizer/alternative/{alternativeId}Request Header:Content-Type: application/json

Body:{ "OpportunityId": 4441, "Name": "Default", "Active": true}


Deleting an AlternativeAn alternative can be deleted by doing a DELETE on following URI:/salesoptimizer/alternative/{alternativeId}Where {alternativeId} is the id of alternative that needs to be deleted.Method: DELETEURI: /salesoptimizer/alternative/{alternativeId}Request Header:Content-Type: application/json


Opportunity Alternative FieldsOpportunity alternative fields are the header attributes of an opportunity alternative. An opportunity alternative field can be a text, number, date or a dimension. Field definitions and their formula to calculate the default value are defined in the opportunity type.

Opportunity Alternative Field REST APIs GET /salesoptimizer/alternative/{alternativeId}/field: Retrieves all field values of an alternative GET /salesoptimizer/alternative/{alternativeId}/field/{fieldIdparam}: Retrieves the field value for given alternative field PUT /salesoptimizer/alternative/{alternativeId}/field/{fieldId}: Updates the given alternative field value

Account Opportunity Alternative Field PropertiesFieldI/ODescription

NameRequiredread-onlyThe name for alternative field.

FieldIdRequiredread-onlyThe FieldId is the id of the field definition defined in the opportunity type.

ValueoptionalRequiredThe value of an alternative field. Value should be numeric for a number field. For a date field value should be in format yyyymmdd. Value for a dimension field should a valid dimension value in PPSS. Value of a text field can be a string, null or an empty string.By default field values are evaluated based on formula configured in field definition. If value of a field needs to be overridden that can be done via PUT action. If an overridden value needs to be cleared and value should be recalculated based on field formula PUT operation can pass the null value and system would reset the overridden value field value will be recalculated based on its formula. For a text field both null and empty string would reset the value of the field.

Retrieving Opportunity Alternative Field ValuesAlternative field values can be retrieved by doing a GET on following URI: /salesoptimizer/alternative/{alternativeId}/field/Where {alternativeId} is id of the alternative for which all field needs to be retrieved.Method: GETURI: /salesoptimizer/alternative/{alternativeId}/field/Request Header:Content-Type: application/json

Response:{ "Fields": [ { "Name": "Effective Start Date", "FieldId": 2111, "Value": "20130101" }, { "Name": "Effective End Date ", "FieldId": 2112, "Value": "20131231" }, { "Name": "Contact Person", "FieldId": 2113, "Value": "James Smith" }, { "Name": "Total Revenue", "FieldId": 2114, "Value": 1,000,000 } ]}

An individual alternative field value can be retrieved by doing a GET on following URI:/salesoptimizer/alternative/{alternativeId}/field/{fieldIdparam}Where {fieldIdparam} is the id of the field or the field name, and {alternativeId} is the id of the alternative for which field value needs to be retrieved.Method: GETURI: / salesoptimizer/alternative/{alternativeId}/field/{fieldId}Request Header:Content-Type: application/json

Response:{ "Name": "Contact Person", "FieldId": 2113, "Value": "James Smith"}

Updating an Opportunity Alternative field valueAn alternative field value can be updated by doing a PUT on following URI: /salesoptimizer/alternative/{alternativeId}/field/{fieldId}Where {fieldId} is the id of the field whose value needs to be updated and {alternativeId} is the id of the alternative to which field belongs.Method: PUTURI: /salesoptimizer/alternative/{alternativeId}/field/{fieldId}Request Header:Content-Type: application/json

Body:{ "Name": "Contact Person", "FieldId": 2113, "Value": "Adam Jones"}


Opportunity Alternative ItemsAn item is defined by the dimensional values. Items may also contain a unit of measure, volume, and values for elements corresponding to the profit model template association. Opportunity Alternative Item REST APIs GET /salesoptimizer/alternative/{alternativeId}/item: Retrieves all items of an alternative GET /salesoptimizer/alternative/{alternativeId}/item/{itemId}: Retrieves an item by Id PATCH /salesoptimizer/alternative/{alternativeId}/item/{itemId}: Updates an item with given properties and values for the properties which are not provided as part of request remains same after PATCH action as they were before PATCH. DELETE/salesoptimizer/alternative/{alternativeId}/item/{itemId}: Deletes an item by Id

Opportunity Alternative Item Field PropertiesFieldI/ODescription

ColumnsoptionalThis list of columns for an item. The columns list is consist of items as a name value pair object. Where name is the name of the element and value is the value for that element. For example an element can be: Score, Price, Discount, Volume etc. And an element can be of type number of string.The value of an element should be numeric for a number element.By default value of elements are evaluated based on formula configured in item profit model. If value of an element needs to be overridden that can be done via PATCH action. If an overridden value needs to be cleared and value should be recalculated based on formula, PATCH operation can pass the null value and system would reset the overridden value for that element and will be recalculated value based on formula in item profit model. For a string element both null and empty string would reset the value of the field.

Idread onlyThe Id of the item auto generated by system.

KeyDimensionsrequiredThe value of dimensions that define an item.

tagoptionalThe tag is a string property on the item. Can be uses to identify items of same scope to be uniquely defined for profitability calculations.

WarningMessageread onlyThe warning message given detail if item is duplicate, had evaluation issue.

Retrieving Opportunity Alternative ItemAlternative items can be retrieved by doing a GET on following URI: /salesoptimizer/alternative/{alternativeId}/item/Where {alternativeId} is id of the alternative for which all items needs to be retrieved.Method: GETURI: /salesoptimizer/alternative/{alternativeId}/item/Request Header:Content-Type: application/json

Response:{ "Items": [ { "KeyDimensions": [ { "DimensionRole": "PRODUCT", "DimensionLevel": "PRODUCT_ID", "DimensionValue": "MDS-9124-PWR" } ], "Columns": [ { "Name": "Volume", "Value": 70 }, { "Name": "Price", "Value": 100.50 } ], "Id": 8111, }, { "KeyDimensions": [ { "DimensionRole": "PRODUCT", "DimensionLevel": "CATEGORY_ID", "DimensionValue": "CX3-10C-FD" } ], "Columns": [ { "Name": "Volume", "Value": 70 }, { "Name": "Price", "Value": } ], "Id": 8112, "WarningMessage": "Item has evaluation error.", "tag": "CategoryItem" } ]}

An individual alternative item can be retrieved by doing a GET on following URI:/salesoptimizer/alternative/{alternativeId}/item/{itemId}Where {itemId} is the id of the item and {alternativeId} is the id of the alternative for which item needs to be retrieved.Method: GETURI: / salesoptimizer/alternative/{alternativeId}/item/{itemId}Request Header:Content-Type: application/json

Response:{ "KeyDimensions": [ { "DimensionRole": "PRODUCT", "DimensionLevel": "PRODUCT_ID", "DimensionValue": "MDS-9124-PWR" } ], "Columns": [ { "Name": "Volume", "Value": 70 }, { "Name": "Price", "Value": 100.50 } ], "Id": 8111}

Updating an Opportunity Alternative ItemAn alternative item column value can be updated by doing a PATCH on following URI: /salesoptimizer/alternative/{alternativeId}/item/{itemId}Where {itemId} is the id of the item which needs to be updated and {alternativeId} is the id of the alternative to which item belongs.Method: PATCHURI: /salesoptimizer/alternative/{alternativeId}/item/{itemId}Request Header:Content-Type: application/json

Body:{ "Columns": [ { "Name": "Volume", "Value": 80 } ], "Id": 8111}

Response:{ "KeyDimensions": [ { "DimensionRole": "PRODUCT", "DimensionLevel": "PRODUCT_ID", "DimensionValue": "MDS-9124-PWR" } ], "Columns": [ { "Name": "Volume", "Value": 80 }, { "Name": "Price", "Value": 100.50 } ], "Id": 8111}

Deleting an Opportunity Alternative ItemAn alternative item can be deleted by doing a DELETE on following URI:/salesoptimizer/alternative/{alternativeId}/item/{itemId}Where {itemId} is the id of item that needs to be deleted and {alternativeId} is the id of the alternative to which item belongs.Method: DELETEURI: /salesoptimizer/alternative/{alternativeId}/item/{itemId}Request Header:Content-Type: application/json


Opportunity Alternative TransitionAn opportunity can be configured to have lifecycle. Lifecycle of an opportunity includes stages and opportunity can be moved into different stages in a lifecycle. An opportunity can be moved into different stage by updating stage for an alternative. When a stage is set on an alternative whole opportunity including all alternatives goes into new stage. Opportunity Alternative Transition REST APIs PUT /salesoptimizer/alternative/{alternativeId}/stage: Moves the opportunity into given stage

Taking transition on an AlternativeAn opportunity can be moved into new stage by doing following PUT: /salesoptimizer/alternative/{alternativeId}/stageWhere {alternativeId} is the id of alternative which needs to be moved into new stage.Method: PUTURI: /salesoptimizer/alternative/{alternativeId}/stageRequest Header:Content-Type: application/json

Body:{ "StageName": "Published"}


AgreementAn agreement is a published opportunity. Agreement REST APIs GET /salesoptimizer/agreement/{agreementId} GET /salesoptimizer/agreement/{agreementId}/attribute GET /salesoptimizer/agreement/{agreementId}/pricingdecision?componentType= {componentTypeUploadCode}&priceLevel={priceLevelUploadCode}Retrieving an AgreementAn agreement can be retrieved by doing a GET on following URI:/salesoptimizer/agreement/{agreementId}Where {agreementId} is the id of the published opportunity.Method: GETURI: /salesoptimizer/agreement/{agreementId}Response:{ "AgreementStructureId": 2001, "Name": "501", "AgreementId": "1000798608", "Version": 2, "AgreementRecordId": 501}

Retrieving all Attribute ValuesThe attribute values of an agreement can be retrieved by doing a GET on following URI:/salesoptimizer/agreement/{agreementId}/attributeWhere {agreementId} is the id of the published opportunity.Method: GETURI: /salesoptimizer/agreement/{agreementId}/attributeResponse:[ { "Name": "Contact", "Value": "John Smith" }]

Retrieving all Pricing DecisionsThe pricing decisions of an agreement can be retrieved by doing a GET on following URI:/salesoptimizer/agreement/{agreementId}/pricingdecision?componentType={componentTypeUploadCode}&priceLevel={priceLevelUploadCode}Where {agreementId} is the id of the published opportunity, {componentTypeUploadCode} and {priceLevelUploadCode} is the upload codes, of the component type and of the pricing level upload code respectively. Method: GETURI:/salesoptimizer/agreement/{agreementId}/pricingdecision?componentType={componentTypeUploadCode}&priceLevel={priceLevelUploadCode}

Response:[ { "Name": "Contact", "Value": "John Smith" }]

Error Handling for REST APIsIf REST APIs encounters an error, system will send error information in response. For example an if alternative transition fails because there are errors in items you will get a message like:Response:{ "Status" : 4500, "Message" : "Unable take opportunity transition, alternative item has errors"}

Contacting PROSPlease report any product questions or incidents on PROSConnect, our self-service customer support portal.PROS Customer SupportWeb Addresshttps://connect.prospricing.com

PROS Product InformationPhone713-335-5151Fax713-335-8144Web Addresshttp://www.prospricing.com

PROS3100 Main Street, Suite 900, Houston, TX 77002-9312 USA

Copyright 2013 PROS Revenue Management, L.P.All information contained within this document is the confidential property of PROS. It is submitted with the understanding that it shall not be disclosed to any third party either in whole or in part without the prior written consent of PROS.No part of this publication may be reproduced, stored in a retrieval system, or transmitted in any form or by any means, electronic, mechanical, photocopying, or otherwise, without the prior written permission of PROS.PROS makes no representations or warranties with respect to the contents hereof and specifically disclaims any implied warranties of merchantability for any particular purpose. Furthermore, PROS reserves the right to revise this publication and to make changes in content hereof without obligation of PROS to notify any person of such revision.TrademarksAll other brands and their products are trademarks or registered trademarks of their respective holders and should be noted as such. This product includes software developed by the Apache Software Foundation (http://www.apache.org/).

Copyright PROS 35

So Rest API Tech Notes

Documents

Transcript of So Rest API Tech Notes