RightsZone

This rest API follows the same model as all APIs for RightsZone. Please Familiarize yourself with these articles to start:

• API Overview
• API Initial Authentication
• Calling the RightsZone API

What this API does

This API inserts or updates both Project (Work) AND Component (Product Format) records at the same time. This API also allows you to load multiple product formats for the same project e.g a HB, PB and ebook for the same Project. 

If you want to insert Components (Products) but link them to an existing Project you need to specify the unique system Id for that Project (either as the SF ID or your own Ext Sys Id). 

End Point

dataload/project/projectcomponents

Input

The input is an array of projectAndComponentDto records where either the projectId and productId OR the extSysProjectId and extSysProductId fields must be sent.

The result of a call to this API for each projectAndComponentDto record in the JSON:

• upserts a record in RZone__Project__c (Project/Work)
• upserts a record in RZone_PSComponent__c (Product Format - ISBN level record)
• links these 2 records together with RZone_PSComponent__c record having a FK to RZone__Project__c

JSON Structure

The JSON is wrapped around a projectAndComponentDetailList entity and you can send one or many records:

{ 

"projectAndComponentDetailList ":[

    {projectAndComponentDto1},

    {projectAndComponentDto2},

    ...

    ]

}  

Data can be: 

• Boolean fields are ‘true’ or ‘false’
• Ids are Salesforce Ids
• Ext Sys Ids are an Id in your system integrating to RightsZone, e.g. your Title Management system.
• String is any text

Required Parameters

At least one of these is parameters is required.

• projectId and productId: the Salesforce record ID
• extSysProjectId and extSysProductId: the unique Id of the project in your own system (generally Title Management System) - can be the primary format ISBN for example or a system uniqueId if you have one. But something that uniquely identifies the Project (title) and Component (Product) over time i.e. is persistent.
• In addition: productShortTitle: Short Title, division: Publisher Division, authorStringInverted Author String Inverted, authorString Author String, legalEntity Legal Entity and productStatus Project Status ARE MANDATORY.  mainFormat Populate Primary Format should be set to TRUE on the Component (Product) that you wish to be treated as the primary format e.g. the HB record NOTE there can only be 1 primary format.

Responses  

• All records you send are returned in the same exact order

• Each row is associated with a success or a failure

• ObjectList will contain all the records inserted for the corresponding row

• In this case, there will be two records one for the Project and one for the Component (Product)

• ProjectId and ComponentId are the corresponding Salesforce Ids of the records you inserted/updated.

{

    "responseList": [

        {

             "status": "Project:Success Product: Success",

            "row": "0",

             "objectList": [

                {

                     "source": "Project Upsert",

                    "sfId": "a0K0O00000YGwfkUAD",

                     "externalId": "Project1"

                },

                {

                     "source": "Component Upsert",

                     "sfId": "a060O00001LUrnBQAT",

                     "externalId": "External Product Id 001jdjdjd"

                }

            ],

            "error": "",

             "projectId": "a0K0O00000YGwfkUAD",

             "projectExternalId": "Project1",

             "productId": "a060O00001LUrnBQAT",

             "productExternalId": "External Product Id 001jdjdjd"

        }

    ]

}

General Error

There is a problem with the API usage/format, the JSON is invalid or the data type of a field is incorrect:

Request example:

{

"TEST":[ { 

}]

}

Response:

{

            [{

                        "status":"failure",

                        "row":"0",

                        "objectList":null,

                        "error":"Your attempt to use the service is not valid”

            }]

}

Data Errors

The API usage is correct however something is wrong with the data. This happens when the data itself is not properly set to be inserted/updated against the project record. For example, if the DivisionId or ProjectId is incorrect then RZ returns an error (Note: sometimes the error doesn’t mention the name of the field failing due to SF limitations).  

[{

                    "status":"Project:failure Product: failure",

                    "row":"0",

                    "objectList":[

                                         {

                                                             "source":"Project Upsert",

                                                             "sfId":null,

                                                             "externalId":"Project1"

                                         },

                                         {

                                                             "source":"Component Upsert",

                                                             "sfId":null,

                                                             "externalId":"External Product Id 001"

                                         }

                    ],

                    "error":"invalid cross reference id -Fields: () -Code: INVALID_CROSS_REFERENCE_KEY Required fields are missing: [PSProject__c] -Fields:(PSProject__c) -Code:REQUIRED_FIELD_MISSING",

                    "projectId":null,

                    "projectExternalId":"Project1",

                    "productId":null,

                    "productExternalId":"External Product Id 001”

}]

Common Issues

See Common API Issues for details of common errors and queries

Note that some fields in RightsZone exist against both the Project (PSProject__c) and the Product Format (PSComponent__c). All fields that fall into this category will populate both Project and Product Format when using this API.

Request Example

{  

            "projectAndComponentDetailList": [{  

                        "projectId": Id (Salesforce Id, FK to PSProject__c type),

                        "productId": Id (Salesforce Id, FK to PSComponent__c type),

                        "extSysProjectId": Your System Id,

                        "extSysProductId": Your System Id,

                        "productShortTitle": String(80),

                        "longTitle": String,

                        "translationRights": Boolean,

                        "themaSubjectCodes": String,

                        "territory": Id (Salesforce Id, FK to PSTerritory__c),

                        "targetMarket": String,

                        "subtitle": String,

                        "rightsReverted": String,

                        "publicationDate": String,

                        "productURL": String,

                        "productStatus": String,

                        "productFormat":String,

                        "productFormatDetail":String,

                        "productavailability":String,

                        "media":String,

                        "priceCurrency":String,

                        "price":Integer,

                        "previousEditionTitle": String,

                        "payOnGross": Boolean,

                        "payEarly": Boolean,

                        "mainFormat": Boolean,

                        "levelAudience": String,

                        "componentType":String,

                        "legalEntity": String,

                        "languageTerms": Id (FK, SF ID to PSLanguageTerms__c),

                        "jacketImageURL": String,

                        "isbn13": String,x

                        "internalSubjectCodes": String,

                        "imprint": String,

                        "illustrationsSummary": String,

                        "extent": String,

                        "englishLanguageReprintRights": Boolean,

                        "editionStatement": String,

                        "editionNumber": Integer,

                        "editedProject": Boolean,

                        "division": Id (SF Id, FK to Account),

                        "copyrightYear": String,

                        "dimensions":String,

                        "bicSubjectString": String,

                        "authorStringInverted": String,

                        "authorString": String,x

                        "approvalOrNotificationRequired": String,

"bisacSubjectString": String,

"genre": String,

"keywords": String,

"originalPublisher": String,

"projectIssn": String,

"projectOrigin": String,

"projectSeries": String,

"publisherEditor": String,

"volumeNumber": Integer,

"proprietorName": String,

"noRightsEB": true,

"noRightsHB": false,

"noRightsPB": true,

"noRightsAllFormats": false,

"subjectGroup": String,

“pmgCode” : String,

“titleCode”: String,

“audienceText”: String,

“archiveFiles” :String,

“keyFeatures”: String,

“shortDescription”: String,

“relatedAncillaries”: String

 “openAccessStatus” : string,

“openAccessfundingBody”: string,

“openAccesslicenseType” : string,

"editorialAssistant": string,

"onSaleDate": string

            }]

}