This Help Center is a preview of a future release. The final Help Center will be available on the Validation date.

Change request APIs

Companies that own or link to Agile Process Teams use these APIs to add, evaluate, and implement process change requests with their internal locations and external Partners on the network. For example, a Manufacturer might need to upgrade equipment at their internal manufacturing locations, or a Supplier might need to streamline the paperwork for their customers to lower cost. Partners must be a member of the Owner company's network to collaborate with the Owner on a change request.

Change requests can be in one of three base workflow states:

To Do – The change request is new and has not been reviewed. Can be transitioned to In Implementation or Closed.
In Implementation – The requested change has been reviewed and is ready for implementation by assigned users. This state can be manually applied. Can be transitioned to Closed.
Closed – The requested change is closed. This state is applied when the resolution is submitted. Can be transitioned back to In Implementation.

Add Change

Owners and Partners use this API to add a new request for a general process change on the Owner company's network, including any initial comments or file attachments. The response returns a generated identifier for the new change request.

New change requests are assigned the ToDo base state by default.

Add Change request

Guidelines

Element				Type	Description
header				–	Required. The request header.
	headerVersion			Integer	Required. The version identifier for the request. Valid value is `1`.
	eventName			String	Required. The fully qualified name of the request event. Valid value is `agile-process-teams:add-change:v5`.
	ownerId			String	Required. The identifier for the Owner company associated with the request.
	appName			String	Required. The application that owns the event. Valid value is `agile-process-teams`.
	processNetworkId			String	Required. The network that contains the change request process. This must be a valid network at the Owner company.
	dataspace			String	Required. The dataspace within the environment where the request is being made. Valid value for the Production and Validation environments is `default`.
payload				–	Required. The request body.
	partnerCompany			Object	Conditionally required if isVisible is `true`. The identifier number and type for the Partner company associated with the change request.
		partnerId		String	The identifier for the Partner company.
		toIdType		Enum	The Partner identifier type. Valid values: `partnerMasterData` `partnerLocationMasterData` `companyMasterData` `companyLocationMasterData`
	isVisible			Boolean	Required. Determines whether process team members from the Partner company associated with the change can view the change request being added. Valid values: `true` – Yes, users from the Partner company associated with the change can view the change request being added. The partnerId cannot be empty. `false` – No, only users from the Owner company can view the change request.
	aptBusinessObjectSummary			String	Required. A brief summary of the change request. Cannot exceed 255 characters.
	aptBusinessObjectDescription			String	A detailed description of the change request. Cannot exceed 5000 characters.
	responsiblePartyAtCompany			String	The identifier for the person from the Owner company that owns the requested change from the Owner's side and is responsible for the change request's implementation. If omitted, defaults to `null` (i.e. the system `Unassigned` user).
	responsibleDepartmentAtCompany			String	The business area of the Owner company that is responsible for the change request's implementation. If omitted, defaults to the job function of the responsible party, if defined for the user; otherwise is `null`. Valid values: `BUSINESS_DEVELOPMENT` – The user responsible for implementing the requested change is part of a Business Development team. `CLINICAL_RESEARCH` – The user responsible for implementing the requested change is part of a Clinical Research team. `CONTRACT_MANAGEMENT` – The user responsible for implementing the requested change is part of a Contract Management team. `CORPORATE_MANAGEMENT` – The user responsible for implementing the requested change is part of a Corporate Management team. `CUSTOMER_SERVICE` – The user responsible for implementing the requested change is part of a Customer Service team. `ENGINEERING` – The user responsible for implementing the requested change is part of an Engineering team. `INFORMATION_TECHNOLOGY` – The user responsible for implementing the requested change is part of an Information Technology (IT) team. `OPERATIONS` – The user responsible for implementing the requested change is part of an Operations team. `PACKAGING` – The user responsible for implementing the requested change is part of a Packaging team. `PRODUCTION_OR_MANUFACTURING` – The user responsible for implementing the requested change is part of a Production team or Manufacturing team. `PROJECT_MANAGEMENT` – The user responsible for implementing the requested change is part of a Project Management team. `PURCHASING` – The user responsible for implementing the requested change is part of a Purchasing team. `QUALITY_ASSURANCE_CONTROL_OR_VALIDATION` – The user responsible for implementing the requested change is part of a Quality Assurance (QA) team, Control team, or Validation team. `RESEARCH_DEVELOPMENT_OR_FORMULATION` – The user responsible for implementing the requested change is part of a Research team, Development team, or Formulation team. `SALES_OR_MARKETING` – The user responsible for implementing the requested change is part of a Sales team or Marketing team. `SUPPLY_CHAIN` – The user responsible for implementing the requested change is part of a Supply Chain team.
	responsiblePartyAtPartner			String	The identifier for the person from the Partner company that owns the requested change from the Partner's side and is responsible for the change request's implementation. If omitted, defaults to `null` (i.e. the system `Unassigned` user).
	responsibleDepartmentAtPartner			String	The business area of the Partner company that is responsible for the change request's implementation. If omitted, defaults to the job function of the responsible party, if defined for the user; otherwise is `null`. Valid values: `BUSINESS_DEVELOPMENT` – The user responsible for implementing the requested change is part of a Business Development team. `CLINICAL_RESEARCH` – The user responsible for implementing the requested change is part of a Clinical Research team. `CONTRACT_MANAGEMENT` – The user responsible for implementing the requested change is part of a Contract Management team. `CORPORATE_MANAGEMENT` – The user responsible for implementing the requested change is part of a Corporate Management team. `CUSTOMER_SERVICE` – The user responsible for implementing the requested change is part of a Customer Service team. `ENGINEERING` – The user responsible for implementing the requested change is part of an Engineering team. `INFORMATION_TECHNOLOGY` – The user responsible for implementing the requested change is part of an Information Technology (IT) team. `OPERATIONS` – The user responsible for implementing the requested change is part of an Operations team. `PACKAGING` – The user responsible for implementing the requested change is part of a Packaging team. `PRODUCTION_OR_MANUFACTURING` – The user responsible for implementing the requested change is part of a Production team or Manufacturing team. `PROJECT_MANAGEMENT` – The user responsible for implementing the requested change is part of a Project Management team. `PURCHASING` – The user responsible for implementing the requested change is part of a Purchasing team. `QUALITY_ASSURANCE_CONTROL_OR_VALIDATION` – The user responsible for implementing the requested change is part of a Quality Assurance (QA) team, Control team, or Validation team. `RESEARCH_DEVELOPMENT_OR_FORMULATION` – The user responsible for implementing the requested change is part of a Research team, Development team, or Formulation team. `SALES_OR_MARKETING` – The user responsible for implementing the requested change is part of a Sales team or Marketing team. `SUPPLY_CHAIN` – The user responsible for implementing the requested change is part of a Supply Chain team.
	currentlyAssignedCompanyUsers			Array	List of one or more users at the Owner company assigned to the change request. If omitted, defaults to `null` (i.e. the system `Unassigned` user).
	currentlyAssignedPartnerUsers			Array	List of one or more users at the Partner company assigned to the change request. If omitted, defaults to `null` (i.e. the system `Unassigned` user).
	businessPriority			Enum	Required. The urgency with which the requested change needs to be implemented. Valid values: `LOW` - The change request has low business priority. `MEDIUM` – The change request has medium business priority. `HIGH` – The change request has high business priority. `CRITICAL` – The change request is critical.
	changeType			String	The type of change being implemented by the change request. Valid values: `SUPPLIER` – The supplier needs to change. `DESIGN` – The design needs to change. `EQUIPMENT` – The equipment needs to change. `FACILITY` – The facility needs to change. `MATERIAL` – The material needs to change. `PROCESS` – The process needs to change. `SPECIFICATION` – The specification needs to change. `DISCREPANCY_CORRECTION` – An existing discrepancy needs to be corrected. `INDIRECT_SUPPLIER` – The indirect supplier needs to change. `OTHER` – The change type is user-defined. If this field is `OTHER`, use the otherChangeType to define the change type.
	otherChangeType			String	If the changeType is `OTHER`, this is the user-defined type of change being implemented by the change request. To prevent corrupted data, the otherChangeType should only be included in the request if the changeType is `OTHER`.
	implementationDueDate			Number	The date and time (in Unix epoch time in milliseconds) that the change request is due to be implemented (e.g. 1622631600). Process team members from the Partner company cannot set this date. If omitted, the date is calculated by adding the default time (in hours) configured for the network to the time the change reqeust was added. For example, if the default implementationRequiredWithinHours is 336 and the current date is 01 Jun 2021, the implementationResponseDueDate is calculated as 14 Jun 2021.
	implementationTeam			String	The name of the location or group overseeing the change request implementation.
	initiatingCompany			Object	The identifier number and type for the company initiating the request.
		toId		String	The identifier for the company initiating the change request. The company must exist in Master Data.
		toIdType		Enum	The identifier type indicating whether the initiating company is an Owner or Partner. Valid values: `companyMasterData` `partnerMasterData`
	subjectMatterExperts			Array	Contains the people designated as experts on subjects related to the change request.
		subjectMatterExpertName		String	The name of the subject matter expert.
		subjectMatterExpertEmail		String	The email of the subject matter expert.
	changeImpact			Object	Contains the ways in which the change request impacts business.
		changeReferenceIdentifiers		Array	The internal reference identifiers used by the Owner or Partner's external system of record to identify the change request (e.g. Partner Change Number: QMS123).
			referenceTransactionType	Enum	The type of reference for the change request. Valid values: `INTERNAL_CHANGE_NUMBER` – The reference ID is an internal change number. `PARTNER_CHANGE_NUMBER` – The reference ID is a partner change number.
			value	String	The value for the selected referenceTransactionType. Cannot exceed 72 characters.
		riskType		String	The type and level of risk associated with the change request. Valid values: `NONTECHNICAL_LOW_RISK` – There is low non-technical risk associated with the change request. `NONTECHNICAL_HIGH_RISK` – There is high non-technical risk associated with the change request. `TECHNICAL_LOW_RISK` – There is low technical risk associated with the change request. `TECHNICAL_HIGH_RISK` – There is high technical risk associated with the change request. `REGULATORY_RISK` – There is regulatory risk associated with the change request. `NO_RISK` – There is no risk associated with the change request. `OTHER` – The risk type is user-defined. If this field is `OTHER`, use the otherRiskType to define the risk type.
		otherRiskType		String	If the riskType is `OTHER`, this is the user-defined type and level of risk being associated with the change request. To prevent corrupted data, the otherRiskType should only be included in the request if the riskType is `OTHER`.
		implementationNeededByDate		Number	The date and time (in Unix epoch time in milliseconds) that the change must be implemented by before the reason for the change impacts the business.
		businessScopeImpact		String	The business function impacted by the change request. Valid values: `HUMAN_HEALTH` – The change request impacts the company's business related to human health. `ANIMAL_HEALTH` – The change request impacts the company's business related to non-human animal health. `RESEARCH_LABS` – The change request impacts the company's research laboratory business. `EXTERNAL_MANUFACTURING` – The change request impacts the company's external manufacturing business. `OTHER` – The business impact of the change request is user-defined. If this field is `OTHER`, use the businessScopeImpact to define the business impact.
		otherBusinessScopeImpact		String	If the businessScopeImpact is `OTHER`, this is the user-defined business function impacted by the change request. To prevent corrupted data, the otherBusinessScopeImpact should only be included in the request if the businessScopeImpact is `OTHER`.
		reasonForChange		String	The reason that the change request must be implemented. Valid values: `IMPROVE_QUALITY_OR_COMPLIANCE` – The change request is a result from an effort to improve quality or achieve compliance. `REQUIRED_CHANGE_FROM_AN_INDIRECT_SUPPLIER` – The change request originated with a requirement from an indirect supplier. `CUSTOMER_REQUEST` – The change request originated with a customer request. `INCREASE_CAPACITY` – The change request is a result of a need to increase capacity. `STREAMLINE_OPERATIONS` – The change request is a result of a need to streamline operations. `SAVE_COSTS` – The change request is a result of a need to lower costs. `REQUIRED_FOR_MANAGEMENT_OR_BUSINESS_NEEDS` – The change request originated with a requirement from management or business. `OTHER` – The reason that the change request must be implemented is user-defined. If this field is `OTHER`, use the otherReasonForChange to define the reason for the change.
		otherReasonForChange		String	If the reasonForChange is `OTHER`, this is the user-defined reason that the change request must be implemented. To prevent corrupted data, the otherReasonForChange should only be included in the request if the reasonForChange is `OTHER`.
		reasonForChangeNotes		String	Any additional descriptions or explanations for the change request and why it must be implemented. Cannot exceed 5000 characters.
		potentialRisks		String	A detailed explanation of other risks potentially associated with the change request. Cannot exceed 5000 characters.
		evaluationsOfChange		String	A summary of the impacts associated with the change request. Cannot exceed 5000 characters.
	createdByPartner			Boolean	Indicates whether the new change request is created by a person from the Partner company. Valid values: `true` – Yes, the new change request is created by a user from the Partner. `false` – No, the new change request is created by a user from the Owner.
	impactedProducts			Array	Identifiers for the one or more products that are affected by the change request.
	impactedLocation			Object	One or more internal or external locations that are impacted by the change request.
		locationId		String	The identifier of the internal or external location that is impacted by the change request. The location must exist in Master Data.
		toIdType		Enum	The location identifier type. Valid values: `companyLocationMasterData` `partnerLocationMasterData`
		locationType		Enum	Indicates whether the impacted location is internal or external. Valid values: `Internal` – The impacted location is an internal location. `External` – The impacted location is an external location.
		locationContact		String	The user that is the regulatory contact for the location.
	relatedProcesses			Object	One or more processes to link to the change request as a related process (e.g. a change request that caused an incident, a previously occurring incident). This must be an existing process in the Owner's network. Process team members from the Partner company can only view and link processes associated to their company.
		processId		String	The identifier for the related process.
		processType		String	The process type of the related process (e.g. `incident`).
		relationship		String	The type of relationship the linked process has to the current change request. Valid values: `RELATES_TO` – The linked process is related to the current change request. `BLOCKS` – The linked process prevents the current change request’s resolution. `BLOCKED_BY` – The current change request prevents the linked process's resolution. `CONTAINS` – The linked process is the parent of the current change request. `CONTAINED_BY` – The current change request is the parent of the linked process. `DEPENDENT_ON` – The linked process affects the current change request's resolution. `DEPENDENCY_FOR` – The current change request affects the linked process's resolution.
	aptCommentBox			Object	Contains any comments or files to attach to the change request.
		aptComment		Array	One or more comments about the change request or explanations for the attachments that the user wants to provide.
			commentText	String	The text of the comment. Cannot exceed 5000 characters.
			visibilityType	Enum	Conditionally required to submit the comment. Determines whether process team members from the Partner company associated with the change request can view the comment. Valid values: `ownerOnly` – No, only users from the Owner company can view the comment. `public` – Yes, users from the Partner company associated with the change request can view the comment.
		addAttachment		Array	One or more relevant files to attach to the change request. Supported file formats are DOC, TXT, CSV, JPEG, PNG, and PDF.
			fileName	String	The name of the file to attach. Cannot exceed 255 characters.
			fileSize	String	The size of the file. Cannot exceed 25MB.
			visibilityType	Enum	Conditionally required to submit the attached file. Determines whether process team members from the Partner company associated with the change request can view the attached file. Valid values: `ownerOnly` – No, only users from the Owner company can view the attached file. `public` – Yes, users from the Partner company associated with the change request can view the attached file.
			requestIdentifier	String	The identifier for the upload request provided by File Import and Export Manager.

Example

Add with required fields only

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
    "header": {
        "headerVersion": 1,
        "eventName": "agile-process-teams:add-change:v5",
        "ownerId": "94f94f37-2772-4b39-8041-9c2dcfcfff82",
        "processNetworkId": "945feb8e-09a7-4fef-9a8a-b3c5b56f87d",
        "appName": "agile-process-teams",
        "dataspace": "default"
    },
    "payload": {
        "aptBusinessObjectSummary": "Scanner Upgrade",
        "isVisible": false,
        "businessPriority": "MEDIUM"
    }
}

Add with all fields

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
{
    "header": {
        "headerVersion": 1,
        "eventName": "agile-process-teams:add-change:v5",
        "ownerId": "94f94f37-2772-4b39-8041-9c2dcfcfff82",
        "processNetworkId": "945feb8e-09a7-4fef-9a8a-b3c5b56f87d",
        "appName": "agile-process-teams",
        "dataspace": "default"
    },    
    "payload": {
        "partnerCompany": {
            "partnerId": "be9c8cea-72bc-459c-97b9-ef3f7c73ccc8",
            "toIdType": "companyMasterData"
        },
        "isVisible": true,
        "aptBusinessObjectSummary": "Scanner Upgrade",
        "aptBusinessObjectDescription": "Replace existing scanners at Warehouse B with upgraded model",
        "responsiblePartyAtCompany": "c75e31c1-a977-42f4-afd1-5cb9468a3b00",
        "responsibleDepartmentAtCompany": "BUSINESS_DEVELOPMENT",
        "responsiblePartyAtPartner": "dab0a960-01d3-4fe1-aad2-696875beeea9",
        "responsibleDepartmentAtPartner": "BUSINESS_DEVELOPMENT",
        "currentlyAssignedPartnerUsers": [
            "c75e31c1-a977-42f4-afd1-5cb9468a3b00"
        ],
        "currentlyAssignedCompanyUsers": [
            "dab0a960-01d3-4fe1-aad2-696875beeea9"
        ],
        "businessPriority": "MEDIUM",
        "changeType": "SUPPLIER",
        "implementationDueDate": 1611981070772,
        "implementationTeam": "implementationTeam",
        "initiatingCompany": {
            "partnerId": "be9c8cea-72bc-459c-97b9-ef3f7c73ccc8",
            "toIdType": "companyMasterData"
        },
        "subjectMatterExpert": [
            {
                "subjectMatterExpertEmail": "BSpitzer@gmail.com",
                "subjectMatterExpertName": "Brent Spitzer"
            }
        ],
        "changeImpact": {
            "changeReferenceIdentifiers": [
                {
                    "referenceTransactionType": "INVOICE_NUMBER",
                    "value": "55512345"
                }
            ],
            "riskType": "NONTECHNICAL_LOW_RISK",
            "implementationNeededByDate": 1611981070772,
            "businessScopeImpact": "OTHER",
            "otherBusinessScopeImpact": "User-Defined Business Scope",
            "reasonForChange": "STREAMLINE_OPERATIONS",
            "reasonForChangeNotes": "Lorem ipsum dolor sit amet. Consectetur adipiscing elitales.",
            "potentialRisks": "potential Risks",
            "evaluationsOfChange": "Evaluations Of Change"
        },
        "createdByPartner": false,
        "productId": [
            "f2ea770f-a4cb-4b3f-86ed-08d12e740d5c",
            "7da13dd1-b0bc-422e-9213-c70206748021"
        ],
        "impactedLocation": [
            {
                "locationId": "113b11be-e74b-4c8d-b7e5-b5503f4828a3",
                "locationType": "companyLocationMasterData",
                "locationContact": "Elias Davis",
                "toIdType": "companyLocationMasterData"
            }
        ],
        "relatedProcesses": [
            {
                "processId": "a02c7f2a-9b95-441a-a2f0-1b1000e10aa2",
                "processType": "Incident"
            }
        ],
        "aptCommentBox": [
            {
                "aptComment": {
                    "commentText": "Lorem ipsum dolor sit amet. Nam nec mi eu tortor suscipit sodales.",
                    "visibilityType": "Internal"
                },
                "addAttachment": [
                    {
                        "fileName": "82kb",
                        "fileSize": "changeScope_Approved.doc",
                        "visibilityType": "Public",
                        "requestIdentifier": "85bb3620-4721-45cc-bb91-d5da7e3824e0"
                    }
                ]
            }
        ]
    }
}

Add Change response

Guidelines

Element		Type	Description
header		–	Required. The response header.
	headerVersion	Integer	Required. The version identifier for the response. Valid value is `1`.
	eventName	String	Required. The fully qualified name of the response event. Valid value is `agile-process-teams:add-change-response:v5`.
	ownerId	String	Required. The identifier for the Owner company associated with the request.
	isErr	Boolean	Required. Indicates whether the request was successful. Valid values: `true` – The request was successful. `false` – The request was not successful. The errCode field provides error information for troubleshooting.
	errCode	String	Required. The status code of the request. `200_OK` indicates that the request was successful.
	errMsg	String	Conditionally required if the call is unsuccessful. The message associated with the error code.
	licensePlate	String	Required. The unique identifier for the request and response instance.
	exceptionName	String	The exception thrown based on the error code. Valid values: `400 BadRequestException` – The request is missing fields or has invalid data. `404 NotFoundException` – The request is referencing an object that APT cannot find.
payload		–	Required. The payload containing the response body. If the call is unsuccessful, payload is `null`.
	id	String	Required. The identifier for the new change request.

Example

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
{
    "header": {
        "headerVersion": 1,
        "eventName": "agile-process-teams:add-change-response:v5",
        "ownerId": "94f94f37-2772-4b39-8041-9c2dcfcfff82",
        "isErr": false,
        "errCode": "200_OK",
        "licensePlate": "qL0BJs"
    },
    "payload": {
        "id": "4ec1229a-d46f-4fc0-878f-188d318db55a"
    }
}

Errors

Element	Error Message	Description
authorization	User does not have permission to add change requests.	The error occurs if the user does not have the Add permission.
processNetworkId	Process Network Id is required.	The error occurs if the source is empty or null.
aptBusinessObjectSummary	Change summary is required.	The error occurs if the source is empty or null.
aptBusinessObjectSummary	Change summary is greater than max length.	The error occurs if the source exceeds the maximum length of 255 characters.
responsiblePartyAtCompany	Invalid user, must be a user of the owning company and a member of the specified process network.	The error occurs if the source is not a process team member from the Owner company of the network specified in the request.
responsiblePartyAtPartner	Invalid user, must be a user of the partner company and a member of the specified process network.	The error occurs if the source is not a process team member from the Partner company of the network specified in the request.
responsibleDepartmentAtCompany	Invalid Responsible Department at [Owning Company], must be one of the supported values.	The error occurs if the source is not a valid value from the enumeration list.
responsibleDepartmentAtPartner	Invalid Responsible Department at Partner Company, must be one of the supported values.	The error occurs if the source is not a valid value from the enumeration list.
currentlyAssignedCompanyUsers	Invalid user, must be a user of the owning company and a member of the specified process network.	The error occurs if the source is not a process team member from the Owner company of the network specified in the request.
currentlyAssignedPartnerUsers	Invalid user, must be a user of the partner company and a member of the specified process network.	The error occurs if the source is not a process team member from the Partner company of the network specified in the request.
businessPriority	Business Priority is required.	The error occurs if the source is empty or null.
businessPriority	Invalid Business Priority, must be one of the supported values.	The error occurs if not a valid value from the enumeration list.
aptBusinessObjectDescription	Change Description is greater than max length.	The error occurs if the source exceeds the maximum length of 5000 characters.
partnerId	Partner is not a valid network node.	The error occurs if the source is not a linked Partner company on the Owner's network.
implementationDueDate	Invalid Implementation Due Date, must be a valid date in the future.	The error occurs if the source is less than the current time of the incident event.
relatedProcesses	Invalid Process ID, must be a valid process ID within the specified process network.	The error occurs if the source is does not exist on the network specified in the request.
aptComment	Comment is greater than max length.	The error occurs if the source exceeds the maximum length of 5000 characters.
aptComment	Comment visibility type must be Public or Internal.	The error occurs if the source is populated and visibilityType does not equal `Public` or `Internal`.
addAttachment	Attachment file size is greater than max size.	The error occurs if the source exceeds the maximum file size of 25MB.
addAttachment	Attachment visibility type must be Public or Internal.	The error occurs if the source is populated and visibilityType does not equal `Public` or `Internal`.

This app also uses standard HTTP response codes. If an error occurs, additional available information regarding the cause of the error is provided in the errMsg element in the relevant response.

Edit Change

Owners and Partners use this API to modify an existing change request with new, updated, or corrected information and documentation (e.g. adding subject matter experts, fixing a typo). There is an Edit permission and a separate Edit a Closed Change permission.

This API is also used to update the process change request workflow state. The change base state can be manually transitioned from ToDo to InImplementation, indicating that the process change has been reviewed and submitted for implementation.

Edit Change request

Use the comment APIs to add, edit, or delete comments and file attachments.

Guidelines

Element				Type	Description
header				–	Required. The request header.
	headerVersion			Integer	Required. The version identifier for the request. Valid value is `1`.
	eventName			String	Required. The fully qualified name of the request event. Valid value is `agile-process-teams:edit-change:v5`.
	ownerId			String	Required. The identifier for the Owner company associated with the request.
	appName			String	Required. The application that owns the event. Valid value is `agile-process-teams`.
	processNetworkId			String	Required. The network that contains the change request process. This must be a valid network at the Owner company.
	dataspace			String	Required. The dataspace within the environment where the request is being made. Valid value for the Production and Validation environments is `default`.
payload				–	Required. The request body.
	id			String	Required. The identifier for the change request to modify.
	partnerCompany			Object	Conditionally required if isVisible is `true`. The identifier number and type for the Partner company associated with the change request.
		partnerId		String	The identifier for the Partner company.
		toIdType		Enum	The Partner identifier type. Valid values: `partnerMasterData` `partnerLocationMasterData` `companyMasterData` `companyLocationMasterData`
	isVisible			Boolean	Determines whether process team members from the Partner company associated with the change can view the change request being added. Valid values: `true` – Yes, users from the Partner company associated with the change can view the change request being added. The partnerId cannot be empty. `false` – No, only users from the Owner company can view the change request.
	aptBusinessObjectSummary			String	A brief summary of the change request. Cannot exceed 255 characters.
	aptBusinessObjectDescription			String	A detailed description of the change request. Cannot exceed 5000 characters.
	responsiblePartyAtCompany			String	The identifier for the person from the Owner company that owns the requested change from the Owner's side and is responsible for the change request's implementation. If omitted, defaults to `null` (i.e. the system `Unassigned` user).
	responsibleDepartmentAtCompany			String	The business area of the Owner company that is responsible for the change request's implementation. If omitted, defaults to the job function of the responsible party, if defined for the user; otherwise is `null`. Valid values: `BUSINESS_DEVELOPMENT` – The user responsible for implementing the requested change is part of a Business Development team. `CLINICAL_RESEARCH` – The user responsible for implementing the requested change is part of a Clinical Research team. `CONTRACT_MANAGEMENT` – The user responsible for implementing the requested change is part of a Contract Management team. `CORPORATE_MANAGEMENT` – The user responsible for implementing the requested change is part of a Corporate Management team. `CUSTOMER_SERVICE` – The user responsible for implementing the requested change is part of a Customer Service team. `ENGINEERING` – The user responsible for implementing the requested change is part of an Engineering team. `INFORMATION_TECHNOLOGY` – The user responsible for implementing the requested change is part of an Information Technology (IT) team. `OPERATIONS` – The user responsible for implementing the requested change is part of an Operations team. `PACKAGING` – The user responsible for implementing the requested change is part of a Packaging team. `PRODUCTION_OR_MANUFACTURING` – The user responsible for implementing the requested change is part of a Production team or Manufacturing team. `PROJECT_MANAGEMENT` – The user responsible for implementing the requested change is part of a Project Management team. `PURCHASING` – The user responsible for implementing the requested change is part of a Purchasing team. `QUALITY_ASSURANCE_CONTROL_OR_VALIDATION` – The user responsible for implementing the requested change is part of a Quality Assurance (QA) team, Control team, or Validation team. `RESEARCH_DEVELOPMENT_OR_FORMULATION` – The user responsible for implementing the requested change is part of a Research team, Development team, or Formulation team. `SALES_OR_MARKETING` – The user responsible for implementing the requested change is part of a Sales team or Marketing team. `SUPPLY_CHAIN` – The user responsible for implementing the requested change is part of a Supply Chain team.
	responsiblePartyAtPartner			String	The identifier for the person from the Partner company that owns the requested change from the Partner's side and is responsible for the change request's implementation. If omitted, defaults to `null` (i.e. the system `Unassigned` user).
	responsibleDepartmentAtPartner			String	The business area of the Partner company that is responsible for the change request's implementation. If omitted, defaults to the job function of the responsible party, if defined for the user; otherwise is `null`. Valid values: `BUSINESS_DEVELOPMENT` – The user responsible for implementing the requested change is part of a Business Development team. `CLINICAL_RESEARCH` – The user responsible for implementing the requested change is part of a Clinical Research team. `CONTRACT_MANAGEMENT` – The user responsible for implementing the requested change is part of a Contract Management team. `CORPORATE_MANAGEMENT` – The user responsible for implementing the requested change is part of a Corporate Management team. `CUSTOMER_SERVICE` – The user responsible for implementing the requested change is part of a Customer Service team. `ENGINEERING` – The user responsible for implementing the requested change is part of an Engineering team. `INFORMATION_TECHNOLOGY` – The user responsible for implementing the requested change is part of an Information Technology (IT) team. `OPERATIONS` – The user responsible for implementing the requested change is part of an Operations team. `PACKAGING` – The user responsible for implementing the requested change is part of a Packaging team. `PRODUCTION_OR_MANUFACTURING` – The user responsible for implementing the requested change is part of a Production team or Manufacturing team. `PROJECT_MANAGEMENT` – The user responsible for implementing the requested change is part of a Project Management team. `PURCHASING` – The user responsible for implementing the requested change is part of a Purchasing team. `QUALITY_ASSURANCE_CONTROL_OR_VALIDATION` – The user responsible for implementing the requested change is part of a Quality Assurance (QA) team, Control team, or Validation team. `RESEARCH_DEVELOPMENT_OR_FORMULATION` – The user responsible for implementing the requested change is part of a Research team, Development team, or Formulation team. `SALES_OR_MARKETING` – The user responsible for implementing the requested change is part of a Sales team or Marketing team. `SUPPLY_CHAIN` – The user responsible for implementing the requested change is part of a Supply Chain team.
	currentlyAssignedCompanyUsers			Array	List of one or more users at the Owner company assigned to the change request. If omitted, defaults to `null` (i.e. the system `Unassigned` user).
	currentlyAssignedPartnerUsers			Array	List of one or more users at the Partner company assigned to the change request. If omitted, defaults to `null` (i.e. the system `Unassigned` user).
	businessPriority			Enum	The urgency with which the requested change needs to be implemented. Valid values: `LOW` - The change request has low business priority. `MEDIUM` – The change request has medium business priority. `HIGH` – The change request has high business priority. `CRITICAL` – The change request is critical.
	changeType			String	The type of change being implemented by the change request. Valid values: `SUPPLIER` – The supplier needs to change. `DESIGN` – The design needs to change. `EQUIPMENT` – The equipment needs to change. `FACILITY` – The facility needs to change. `MATERIAL` – The material needs to change. `PROCESS` – The process needs to change. `SPECIFICATION` – The specification needs to change. `DISCREPANCY_CORRECTION` – An existing discrepancy needs to be corrected. `INDIRECT_SUPPLIER` – The indirect supplier needs to change. `OTHER` – The change type is user-defined. If this field is `OTHER`, use the otherChangeType to define the change type.
	otherChangeType			String	If the changeType is `OTHER`, this is the user-defined type of change being implemented by the change request. To prevent corrupted data, the otherChangeType should only be included in the request if the changeType is `OTHER`.
	implementationDueDate			Number	The date and time (in Unix epoch time in milliseconds) that the change request is due to be implemented (e.g. 1622631600). Process team members from the Partner company cannot set this date. If omitted, the date is calculated by adding the default time (in hours) configured for the network to the time the change reqeust was added. For example, if the default implementationRequiredWithinHours is 336 and the current date is 01 Jun 2021, the implementationResponseDueDate is calculated as 14 Jun 2021.
	implementationTeam			String	The name of the location or group overseeing the change request implementation.
	initiatingCompany			Object	The identifier number and type for the company initiating the request.
		toId		String	The identifier for the company initiating the change request. The company must exist in Master Data.
		toIdType		Enum	The identifier type indicating whether the initiating company is an Owner or Partner. Valid values: `companyMasterData` `partnerMasterData`
	subjectMatterExperts			Array	Contains the people designated as experts on subjects related to the change request.
		subjectMatterExpertName		String	The name of the subject matter expert.
		subjectMatterExpertEmail		String	The email of the subject matter expert.
	changeImpact			Object	Contains the ways in which the change request impacts business.
		changeReferenceIdentifiers		Array	The internal reference identifiers used by the Owner or Partner's external system of record to identify the change request (e.g. Partner Change Number: QMS123).
			referenceTransactionType	Enum	The type of reference for the change request. Valid values: `INTERNAL_CHANGE_NUMBER` – The reference ID is an internal change number. `PARTNER_CHANGE_NUMBER` – The reference ID is a partner change number.
			value	String	The value for the selected referenceTransactionType. Cannot exceed 72 characters.
		riskType		String	The type and level of risk associated with the change request. Valid values: `NONTECHNICAL_LOW_RISK` – There is low non-technical risk associated with the change request. `NONTECHNICAL_HIGH_RISK` – There is high non-technical risk associated with the change request. `TECHNICAL_LOW_RISK` – There is low technical risk associated with the change request. `TECHNICAL_HIGH_RISK` – There is high technical risk associated with the change request. `REGULATORY_RISK` – There is regulatory risk associated with the change request. `NO_RISK` – There is no risk associated with the change request. `OTHER` – The risk type is user-defined. If this field is `OTHER`, use the otherRiskType to define the risk type.
		otherRiskType		String	If the riskType is `OTHER`, this is the user-defined type and level of risk being associated with the change request. To prevent corrupted data, the otherRiskType should only be included in the request if the riskType is `OTHER`.
		implementationNeededByDate		Number	The date and time (in Unix epoch time in milliseconds) that the change must be implemented by before the reason for the change impacts the business.
		businessScopeImpact		String	The business function impacted by the change request. Valid values: `HUMAN_HEALTH` – The change request impacts the company's business related to human health. `ANIMAL_HEALTH` – The change request impacts the company's business related to non-human animal health. `RESEARCH_LABS` – The change request impacts the company's research laboratory business. `EXTERNAL_MANUFACTURING` – The change request impacts the company's external manufacturing business. `OTHER` – The business impact of the change request is user-defined. If this field is `OTHER`, use the businessScopeImpact to define the business impact.
		otherBusinessScopeImpact		String	If the businessScopeImpact is `OTHER`, this is the user-defined business function impacted by the change request. To prevent corrupted data, the otherBusinessScopeImpact should only be included in the request if the businessScopeImpact is `OTHER`.
		reasonForChange		String	The reason that the change request must be implemented. Valid values: `IMPROVE_QUALITY_OR_COMPLIANCE` – The change request is a result from an effort to improve quality or achieve compliance. `REQUIRED_CHANGE_FROM_AN_INDIRECT_SUPPLIER` – The change request originated with a requirement from an indirect supplier. `CUSTOMER_REQUEST` – The change request originated with a customer request. `INCREASE_CAPACITY` – The change request is a result of a need to increase capacity. `STREAMLINE_OPERATIONS` – The change request is a result of a need to streamline operations. `SAVE_COSTS` – The change request is a result of a need to lower costs. `REQUIRED_FOR_MANAGEMENT_OR_BUSINESS_NEEDS` – The change request originated with a requirement from management or business. `OTHER` – The reason that the change request must be implemented is user-defined. If this field is `OTHER`, use the otherReasonForChange to define the reason for the change.
		otherReasonForChange		String	If the reasonForChange is `OTHER`, this is the user-defined reason that the change request must be implemented. To prevent corrupted data, the otherReasonForChange should only be included in the request if the reasonForChange is `OTHER`.
		reasonForChangeNotes		String	Any additional descriptions or explanations for the change request and why it must be implemented. Cannot exceed 5000 characters.
		potentialRisks		String	A detailed explanation of other risks potentially associated with the change request. Cannot exceed 5000 characters.
		evaluationsOfChange		String	A summary of the impacts associated with the change request. Cannot exceed 5000 characters.
	impactedProducts			Array	Identifiers for the one or more products that are affected by the change request.
	impactedLocation			Object	One or more internal or external locations that are impacted by the change request.
		locationId		String	The identifier of the internal or external location that is impacted by the change request. The location must exist in Master Data.
		toIdType		Enum	The location identifier type. Valid values: `companyLocationMasterData` `partnerLocationMasterData`
		locationType		Enum	Indicates whether the impacted location is internal or external. Valid values: `Internal` – The impacted location is an internal location. `External` – The impacted location is an external location.
		locationContact		String	The user that is the regulatory contact for the location.
	relatedProcesses			Object	One or more processes to link to the change request as a related process (e.g. a change request that caused an incident, a previously occurring incident). This must be an existing process in the Owner's network. Process team members from the Partner company can only view and link processes associated to their company.
		processId		String	The identifier for the related process.
		processType		String	The process type of the related process (e.g. `incident`).
		relationship		String	The type of relationship the linked process has to the current change request. Valid values: `RELATES_TO` – The linked process is related to the current change request. `BLOCKS` – The linked process prevents the current change request’s resolution. `BLOCKED_BY` – The current change request prevents the linked process's resolution. `CONTAINS` – The linked process is the parent of the current change request. `CONTAINED_BY` – The current change request is the parent of the linked process. `DEPENDENT_ON` – The linked process affects the current change request's resolution. `DEPENDENCY_FOR` – The current change request affects the linked process's resolution.
	newBaseState			Enum	Transitions the base workflow state of the change request from To Do to In Implementation. This cannot be reversed; requests in the In Implementation state can only be transitioned to Closed using the Close Change request. The following must be true to update the change request state: The currentBaseState must be `ToDo`. The responsibleDepartmentAtCompany cannot be blank or `null`. Valid value is `InImplementation`.

Example

Edit base state

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
    "header": {
        "headerVersion": 1,
        "eventName": "agile-process-teams:edit-change:v5",
        "ownerId": "94f94f37-2772-4b39-8041-9c2dcfcfff82",
        "processNetworkId": "945feb8e-09a7-4fef-9a8a-b3c5b56f87d",
        "appName": "agile-process-teams",
        "dataspace": "default"
    },
    "payload": {
        "id": "4ec1229a-d46f-4fc0-878f-188d318db55a",
        "isVisible": false,
        "newBaseState": "InImplementation"
    }
}

Edit with updated Partner and impact information

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
{
    "header": {
        "headerVersion": 1,
        "eventName": "agile-process-teams:edit-change:v5",
        "ownerId": "94f94f37-2772-4b39-8041-9c2dcfcfff82",
        "processNetworkId": "945feb8e-09a7-4fef-9a8a-b3c5b56f87d",
        "appName": "agile-process-teams",
        "dataspace": "default"
    },
    "payload": {
        "id": "4ec1229a-d46f-4fc0-878f-188d318db55a",
        "partnerCompany": {
            "partnerId": "be9c8cea-72bc-459c-97b9-ef3f7c73ccc8",
            "toIdType": "companyMasterData"
        },
        "isVisible": true,
        "currentlyAssignedCompanyUsers": [
            "dab0a960-01d3-4fe1-aad2-696875beeea9",
            "a02c7f2a-9b95-441a-a2f0-1b1000e10aa2"
        ],
        "initiatingCompany": {
            "toId": "f71076c3-2287-475f-a9b2-7cb6854045ba",
            "toIdType": "companyMasterData"
        },
        "subjectMatterExpert": [
            {
                "subjectMatterExpertEmail": "John.Stephens@kendall.com",
                "subjectMatterExpertName": "John Stephens"
            }
        ],  
        "changeImpact":{
            "changeReferenceIdentifiers": [
                {
                    "referenceTransactionType": "INVOICE_NUMBER",
                    "value": "55512345"
                }
            ],
            "riskType": "NONTECHNICAL_LOW_RISK",
            "implementationNeededByDate": 1611981070772,
            "businessScopeImpact": "OTHER",
            "otherBusinessScopeImpact": "User-Defined Business Scope",
            "reasonForChange": "STREAMLINE_OPERATIONS",
            "reasonForChangeNotes": "Lorem ipsum dolor sit amet. Consectetur adipiscing elitales.",
            "potentialRisks": "potential Risks",
            "evaluationsOfChange": "Evaluations Of Change"
        },
        "impactedLocation": [
            {
                "locationId": "113b11be-e74b-4c8d-b7e5-b5503f4828a3",
                "locationType": "companyLocationMasterData",
                "locationContact": "Elias Davis",
                "toIdType": "companyLocationMasterData"
            }
        ]
    }
}

Edit Change response

Guidelines

Element		Type	Description
header		–	Required. The response header.
	headerVersion	Integer	Required. The version identifier for the response. Valid value is `1`.
	eventName	String	Required. The fully qualified name of the response event. Valid value is `agile-process-teams:edit-change-response:v5`.
	ownerId	String	Required. The identifier for the Owner company associated with the request.
	isErr	Boolean	Required. Indicates whether the request was successful. Valid values: `true` – The request was successful. `false` – The request was not successful. The errCode field provides error information for troubleshooting.
	errCode	String	Required. The status code of the request. `200_OK` indicates that the request was successful.
	errMsg	String	Conditionally required if the call is unsuccessful. The message associated with the error code.
	licensePlate	String	Required. The unique identifier for the request and response instance.
	exceptionName	String	The exception thrown based on the error code. Valid values: `400 BadRequestException` – The request is missing fields or has invalid data. `404 NotFoundException` – The request is referencing an object that APT cannot find.
payload		–	Required. The payload containing the response body. If the call is unsuccessful, payload is `null`.
	id	String	Required. The identifier for the modified change request.

Example

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
{
    "header": {
        "headerVersion": 1,
        "eventName": "agile-process-teams:edit-change-response:v5",
        "ownerId": "94f94f37-2772-4b39-8041-9c2dcfcfff82",
        "isErr": false,
        "errCode": "200_OK",
        "licensePlate": "IR4cxa"
    },
    "payload": {
        "id": "4ec1229a-d46f-4fc0-878f-188d318db55a"
    }
}

Errors

Element	Error Message	Description
authorization	User does not have permission to edit change requests.	The error occurs if the user does not have the Edit permission.
authorization	User does not have permission to edit change requests that are in a Closed state.	The error occurs if the user does not have the Edit a Closed Change Request permission.
processNetworkId	Process Network ID is required.	The error occurs if the source is empty or null.
id	Process ID is required.	The error occurs if the source is empty or null.
aptBusinessObjectSummary	Incident summary is greater than max length.	The error occurs if the source exceeds the maximum length of 255 characters.
responsiblePartyAtCompany	Invalid user, must be a user of the owning company and a member of the specified process network.	The error occurs if the source is not a process team member from the Owner company of the network specified in the request.
responsiblePartyAtPartner	Invalid user, must be a user of the partner company and a member of the specified process network.	The error occurs if the source is not a process team member from the Partner company of the network specified in the request.
responsibleDepartmentAtCompany	Invalid Responsible Department at [Owning Company], must be one of the supported values.	The error occurs if the source is not a valid value from the enumeration list.
responsibleDepartmentAtPartner	Invalid Responsible Department at Partner Company, must be one of the supported values.	The error occurs if the source is not a valid value from the enumeration list.
currentlyAssignedCompanyUsers	Invalid user, must be a user of the owning company and a member of the specified process network.	The error occurs if the source is not a process team member from the Owner company of the network specified in the request.
currentlyAssignedPartnerUsers	Invalid user, must be a user of the partner company and a member of the specified process network.	The error occurs if the source is not a process team member from the Partner company of the network specified in the request.
businessPriority	Invalid Business Priority, must be one of the supported values.	The error occurs if the source is not a valid value from the enumeration list.
aptBusinessObjectDescription	Change Description is greater than max length.	The error occurs if the source exceeds the maximum length of 5000 characters.
newBaseState	Responsible Party at [Owning Company] must be assigned in order to move the Change Request to In Implementation.	The error occurs if the source equals `InImplementation` and responsiblePartyAtOwner is blank or null.
newBaseState	Invalid Base State, only 'InImplementation' is valid.	The error occurs if the source does not equal `InImplementation`.

This app also uses standard HTTP response codes. If an error occurs, additional available information regarding the cause of the error is provided in the errMsg element in the relevant response.

Copy Change

Owners and Partners use this API to copy an existing change request to the network. Boolean fields determine which section values to copy to from the original to the new change request (e.g. copy all values from the General section but not the Reference IDs section of the original change request).

The new change request is assigned the ToDo base state.

Copy Change request

Guidelines

Element		Type	Description
header		–	Required. The request header.
	headerVersion	Integer	Required. The version identifier for the request. Valid value is `1`.
	eventName	String	Required. The fully qualified name of the request event. Valid value is `agile-process-teams:copy-change:v2`.
	ownerId	String	Required. The identifier for the Owner company associated with the request.
	appName	String	Required. The application that owns the event. Valid value is `agile-process-teams`.
	processNetworkId	String	Required. The network that contains the change request process. This must be a valid network at the Owner company.
	dataspace	String	Required. The dataspace within the environment where the request is being made. Valid value for the Production and Validation environments is `default`.
payload		–	Required. The request body.
	id	String	Required. The identifier for the existing change request to copy.
	isVisible	Boolean	Required. Determines whether process team members from the Partner company associated with the change can view the change request being added. Valid values: `true` – Yes, users from the Partner company associated with the change can view the change request being added. `false` – No, only users from the Owner company can view the change request.
	aptBusinessObjectSummary	String	Required. A brief summary of the change request. Cannot exceed 255 characters.
	copyPartnerInfo	Boolean	Required. Indicates whether to copy the Partner section values from the original change request to the new change request. Valid values: `true` - Yes, copy all Partner section values to the new change request. `false` - No, do not copy the Partner section values to the new change request.
	copyPartnerInfo	Boolean	Required. Indicates whether to copy the Partner section values from the original change request to the new change request. Valid values: `true` - Yes, copy all Partner section values to the new change request. `false` - No, do not copy the Partner section values to the new change request.
	copyImpactInfo	Boolean	Required. Indicates whether to copy the Impact section values from the original change request to the new change request. Valid values: `true` - Yes, copy all Impact section values to the new change request. `false` - No, do not copy the Impact section values to the new change request.
	copyReferenceIds	Boolean	Required. Indicates whether all Reference ID values are copied from the original change request to the new change request. Valid values: `true` - Yes, copy all Reference ID values to the new change request. `false` - No, do not copy the Reference ID values to the new change request.
	copyRelatedProcesses	Boolean	Required. Indicates whether all Related Processes values are copied from the original change request to the new change request. Valid values: `true` - Yes, copy all Related Processes values to the new change request. `false` - No, do not copy the Related Processes values to the new change request.

Example

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
    "header": {        
        "headerVersion": 1,
        "eventName": "agile-process-teams:copy-change:v2",
        "ownerId": "94f94f37-2772-4b39-8041-9c2dcfcfff82",
        "processNetworkId": "945feb8e-09a7-4fef-9a8a-b3c5b56f87d",
        "appName": "agile-process-teams",
        "dataspace": "default"
    },
    "payload": {
        "id": "945feb8e-09a7-4fef-9a8a-b3c5b56f87d3",
        "isVisible": true,
        "aptBusinessObjectSummary": "Make a copy of a change",
        "copyParterInfo": false,
        "copyGeneralInfo": true,
        "copyImpactInfo": true,
        "copyReferenceIds": false,
        "copyRelatedProcesses": true
    }
}

Copy Change response

Guidelines

Element		Type	Description
header		–	Required. The response header.
	headerVersion	Integer	Required. The version identifier for the response. Valid value is `1`.
	eventName	String	Required. The fully qualified name of the response event. Valid value is `agile-process-teams:copy-change-response:v2`.
	ownerId	String	Required. The identifier for the Owner company associated with the request.
	isErr	Boolean	Required. Indicates whether the request was successful. Valid values: `true` – The request was successful. `false` – The request was not successful. The errCode field provides error information for troubleshooting.
	errCode	String	Required. The status code of the request. `200_OK` indicates that the request was successful.
	errMsg	String	Conditionally required if the call is unsuccessful. The message associated with the error code.
	licensePlate	String	Required. The unique identifier for the request and response instance.
	exceptionName	String	The exception thrown based on the error code. Valid values: `400 BadRequestException` – The request is missing fields or has invalid data. `404 NotFoundException` – The request is referencing an object that APT cannot find.
payload		–	Required. The payload containing the response body. If the call is unsuccessful, payload is `null`.
	id	String	Required. The identifier for the new change request.

Example

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
{
    "header": {
        "headerVersion": 1,
        "eventName": "agile-process-teams:copy-change-response:v2",
        "ownerId": "94f94f37-2772-4b39-8041-9c2dcfcfff82",
        "isErr": false,
        "errCode": "200_OK",
        "licensePlate": "i4XDap"
    },
    "payload": {
        "id": "c8fae272-faa9-4f51-9a49-68f67930d4db"
    }
}

Errors

Element	Error Message	Description
authorization	User does not have permission to copy change.	The error occurs if the user does not have the Copy Change Request permission.
id	Process ID is required.	The error occurs is the source is empty or null.
aptBusinessObjectSummary	Summary is required.	The error occurs is the source is empty or null.
copyGeneralInfo	Copy General Information value must be True or False.	The error occurs if the source does not equal `true` or `false`.
copyPartnerInfo	Copy Partner Information value must be True or False.	The error occurs if the source does not equal `true` or `false`.
copyImpactInfo	Copy Impact Information value must be True or False.	The error occurs if the source does not equal `true` or `false`.
copyReferenceIds	Copy Reference Identifiers value must be True or False.	The error occurs if the source does not equal `true` or `false`.
copyRelatedProcesses	Copy Related Processes value must be True or False.	The error occurs if the source does not equal `true` or `false`.

This app also uses standard HTTP response codes. If an error occurs, additional available information regarding the cause of the error is provided in the errMsg element in the relevant response.

Close Change

Owners and Partners use this API to close an existing change request. A closing statement and resolution type must be provided.

The closed request transitions from its current state (either ToDo or InImplementation) to a Closedstate. Closed change requests can be edited or reopened by users with the requisite permissions.

Close Change request

Guidelines

Element				Type	Description
header				–	Required. The request header.
	headerVersion			Integer	Required. The version identifier for the request. Valid value is `1`.
	eventName			String	Required. The fully qualified name of the request event. Valid value is `agile-process-teams:close-change:v3`.
	ownerId			String	Required. The identifier for the Owner company associated with the request.
	appName			String	Required. The application that owns the event. Valid value is `agile-process-teams`.
	processNetworkId			String	Required. The network that contains the change request process. This must be a valid network at the Owner company.
	dataspace			String	Required. The dataspace within the environment where the request is being made. Valid value for the Production and Validation environments is `default`.
payload				–	Required. The request body.
	id			String	Required. The identifier for the existing change request to close.
	resolutionType			Enum	Required.The reason why the change request is being closed. Valid values depend on the current base state of the change request: If currentBaseState = `InImplementation`, valid values: `ACCEPTED` – The change request has been accepted, implemented, and closed. `ACCEPTED_WITH_QUALIFICATION` – The change request has been accepted, implemented with one or more adjustments, and closed. `REJECTED` –The change request has been rejected. `OTHER` – The resolution is user-defined in otherResolutionType. If currentBaseState = `ToDo`, valid value: `NOT_APPLICABLE` – The change request has been closed because the request is not applicable. `OTHER` – The resolution is user-defined in otherResolutionType.
	otherResolutionType			String	If resolutionType is `OTHER`, this is the user-defined resolution type. To prevent corrupted data, otherResolutionType should only be included in the request if resolutionType is `OTHER`.
	closingStatement			String	Any final closing statement about the change request and its closure. Cannot exceed 5000 characters.
	aptCommentBox			Object	Required. Additional information to include in the closure of the change request.
		aptComment		Array	Required. The final comment to provide as the closing statement for the change request.
			commentText	String	Required. The closing statement text. Cannot exceed 5000 characters.
			visibilityType	Enum	Conditionally required to submit the comment. Determines whether process team members from the Partner company associated with the change request can view the comment. Valid values: `ownerOnly` – No, only users from the Owner company can view the comment. `public` – Yes, users from the Partner company associated with the change request can view the comment.
		addAttachment		Array	One or more relevant files to attach to the change request. Supported file formats are DOC, TXT, CSV, JPEG, PNG, and PDF.
			fileName	String	The name of the file to attach. Cannot exceed 255 characters.
			fileSize	String	The size of the file. Cannot exceed 25MB.
			visibilityType	Enum	Conditionally required to submit the attached file. Determines whether process team members from the Partner company associated with the change request can view the attached file. Valid values: `ownerOnly` – No, only users from the Owner company can view the attached file. `public` – Yes, users from the Partner company associated with the change request can view the attached file.
			requestIdentifier	String	The identifier for the upload request provided by File Import and Export Manager.

Example

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
    "header": {
        "headerVersion": 1,
        "eventName": "agile-process-teams:close-change:v3",
        "ownerId": "94f94f37-2772-4b39-8041-9c2dcfcfff82",
        "processNetworkId": "945feb8e-09a7-4fef-9a8a-b3c5b56f87d",
        "appName": "agile-process-teams",
        "dataspace": "default"
    },
    "payload": {
        "id": "c8fae272-faa9-4f51-9a49-68f67930d4db",
        "resolutionType": "ACCEPTED",
        "aptCommentBox": {
            "aptComment": {
                "commentText": "Closing Request 001. Requested changes approved and complete.",
                "visibilityType": "Public"
            }
        }
    }
}

Close Change response

Guidelines

Element		Type	Description
header		–	Required. The response header.
	headerVersion	Integer	Required. The version identifier for the response. Valid value is `1`.
	eventName	String	Required. The fully qualified name of the response event. Valid value is `agile-process-teams:close-change-response:v3`.
	ownerId	String	Required. The identifier for the Owner company associated with the request.
	isErr	Boolean	Required. Indicates whether the request was successful. Valid values: `true` – The request was successful. `false` – The request was not successful. The errCode field provides error information for troubleshooting.
	errCode	String	Required. The status code of the request. `200_OK` indicates that the request was successful.
	errMsg	String	Conditionally required if the call is unsuccessful. The message associated with the error code.
	licensePlate	String	Required. The unique identifier for the request and response instance.
	exceptionName	String	The exception thrown based on the error code. Valid values: `400 BadRequestException` – The request is missing fields or has invalid data. `404 NotFoundException` – The request is referencing an object that APT cannot find.
payload		–	Required. The payload containing the response body. If the call is unsuccessful, payload is `null`.
	id	String	Required. The identifier for the closed change request.
	message	String	Required. The message confirming that the change request was closed.

Example

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
    "header": {
        "headerVersion": 1,
        "eventName": "agile-process-teams:close-change-response:v3",
        "ownerId": "94f94f37-2772-4b39-8041-9c2dcfcfff82",
        "isErr": false,
        "errCode": "200_OK",
        "licensePlate": "EU8ZpM"
    },
    "payload": {
        "id": "c8fae272-faa9-4f51-9a49-68f67930d4db",
        "message": "Change request closed successfully."
    }
}

Errors

Element	Error Message	Description
authorization	User does not have permission to close changes.	The error occurs if the user does not have the Close Change Request permission.
id	Process ID is required.	The error occurs if the source is empty or null.
resolutionType	Resolution Type is required.	The error occurs if the source is empty or null.
resolutionType	Invalid Resolution Type, must be one of the supported values.	The error occurs if the source is not a valid value from the enumeration list.
isReoccurring	Reoccurring Incident value must be True or False.	The error occurs if the source does not equal `true` or `false`.
aptComment	Closing Statement is required.	The error occurs if the source is empty or null.
aptComment	Closing Statement is greater than max length.	The error occurs if the source exceeds the maximum length of 5000 characters.
aptComment	Closing Statement visibility type must be Public or Internal.	The error occurs if the source is populated and visibilityType does not equal `Public` or `Internal`.
addAttachment	Attachment file size is greater than max size.	The error occurs if the source exceeds the maximum file size of 25MB.
addAttachment	Attachment visibility type must be Public or Internal.	The error occurs if the source is populated and visibilityType does not equal `Public` or `Internal`.

This app also uses standard HTTP response codes. If an error occurs, additional available information regarding the cause of the error is provided in the errMsg element in the relevant response.

Reopen Change

Owners use this API to reopen a closed change request. The response returns the identifier for the reopened change request with all information intact, and the base state updates from Closed to InImplementation. Reopened requests cannot be transitioned back to the initial ToDo base state.

Reopen Change request

Guidelines

Element				Type	Description
header				–	Required. The request header.
	headerVersion			Integer	Required. The version identifier for the request. Valid value is `1`.
	eventName			String	Required. The fully qualified name of the request event. Valid value is `agile-process-teams:reopen-change:v1`.
	ownerId			String	Required. The identifier for the Owner company associated with the request.
	appName			String	Required. The application that owns the event. Valid value is `agile-process-teams`.
	processNetworkId			String	Required. The network that contains the change request process. This must be a valid network at the Owner company.
	dataspace			String	Required. The dataspace within the environment where the request is being made. Valid value for the Production and Validation environments is `default`.
payload				–	Required. The request body.
	id			String	Required. The identifier for the closed change request to reopen.
	aptCommentBox			Object	Contains any comments or files to attach to the change request.
		aptComment		Array	One or more comments about the change request or explanations for the attachments that the user wants to provide.
			commentText	String	The text of the comment. Cannot exceed 5000 characters.
			visibilityType	Enum	Conditionally required to submit the comment. Determines whether process team members from the Partner company associated with the change request can view the comment. Valid values: `ownerOnly` – No, only users from the Owner company can view the comment. `public` – Yes, users from the Partner company associated with the change request can view the comment.
		addAttachment		Array	One or more relevant files to attach to the change request. Supported file formats are DOC, TXT, CSV, JPEG, PNG, and PDF.
			fileName	String	The name of the file to attach. Cannot exceed 255 characters.
			fileSize	String	The size of the file. Cannot exceed 25MB.
			visibilityType	Enum	Conditionally required to submit the attached file. Determines whether process team members from the Partner company associated with the change request can view the attached file. Valid values: `ownerOnly` – No, only users from the Owner company can view the attached file. `public` – Yes, users from the Partner company associated with the change request can view the attached file.
			requestIdentifier	String	The identifier for the upload request provided by File Import and Export Manager.

Example

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
    "header": {
        "headerVersion": 1,
        "eventName": "agile-process-teams:reopen-change:v1",
        "ownerId": "94f94f37-2772-4b39-8041-9c2dcfcfff82",
        "processNetworkId": "945feb8e-09a7-4fef-9a8a-b3c5b56f87d",
        "appName": "agile-process-teams",
        "dataspace": "default"
    },
    "payload": {
        "id": "c8fae272-faa9-4f51-9a49-68f67930d4db",
        "aptCommentBox": {
            "aptComment": {
                "commentText": "Reopening Change Request 001",
                "visibilityType": "Internal"
            }
        }
    }
}

Reopen Change response

Guidelines

Element		Type	Description
header		–	Required. The response header.
	headerVersion	Integer	Required. The version identifier for the response. Valid value is `1`.
	eventName	String	Required. The fully qualified name of the response event. Valid value is `agile-process-teams:reopen-change-response:v1`.
	ownerId	String	Required. The identifier for the Owner company associated with the request.
	isErr	Boolean	Required. Indicates whether the request was successful. Valid values: `true` – The request was successful. `false` – The request was not successful. The errCode field provides error information for troubleshooting.
	errCode	String	Required. The status code of the request. `200_OK` indicates that the request was successful.
	errMsg	String	Conditionally required if the call is unsuccessful. The message associated with the error code.
	licensePlate	String	Required. The unique identifier for the request and response instance.
	exceptionName	String	The exception thrown based on the error code. Valid values: `400 BadRequestException` – The request is missing fields or has invalid data. `404 NotFoundException` – The request is referencing an object that APT cannot find.
payload		–	Required. The payload containing the response body. If the call is unsuccessful, payload is `null`.
	id	String	Required. The identifier for the reopened change request.
	message	String	Required. The message indicating the change request is reopened.

Example

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
    "header": {
        "headerVersion": 1,
        "eventName": "agile-process-teams:reopen-change-response:v1",
        "ownerId": "94f94f37-2772-4b39-8041-9c2dcfcfff82",
        "isErr": false,
        "errCode": "200_OK",
        "licensePlate": "2rw4zz"
    },
    "payload": {
        "id": "c8fae272-faa9-4f51-9a49-68f67930d4db",
        "message": "Change request reopened successfully."
    }
}

Errors

Element	Error Message	Description
authorization	User does not have permission to reopen changes.	The error occurs if the user does not have the Reopen Change Request permission.
id	Process ID is required.	The error occurs if the source is empty or null.
aptComment	Comment is greater than max length.	The error occurs if the source exceeds the maximum length of 5000 characters.
aptComment	Comment visibility type must be Public or Internal.	The error occurs if the source is populated and visibilityType does not equal `Public` or `Internal`.
addAttachment	Attachment file size is greater than max size.	The error occurs if the source exceeds the maximum file size of 25MB.
addAttachment	Attachment visibility type must be Public or Internal.	The error occurs if the source is populated and visibilityType does not equal `Public` or `Internal`.

This app also uses standard HTTP response codes. If an error occurs, additional available information regarding the cause of the error is provided in the errMsg element in the relevant response.

Add Comment For Change

Owners and Partners use this API to add comments and attach files to an existing change request.

Add Comment For Change request

Guidelines

Element				Type	Description
header				–	Required. The request header.
	headerVersion			Integer	Required. The version identifier for the request. Valid value is `1`.
	eventName			String	Required. The fully qualified name of the request event. Valid value is `agile-processteams:-add-comment-for-change:v1`.
	ownerId			String	Required. The identifier for the Owner company associated with the request.
	appName			String	Required. The application that owns the event. Valid value is `agile-process-teams`.
	processNetworkId			String	Required. The network that contains the change request process. This must be a valid network at the Owner company.
	dataspace			String	Required. The dataspace within the environment where the request is being made. Valid value for the Production and Validation environments is `default`.
payload				–	Required. The request body.
	processId			String	Required. The identifier for the change request being commented on.
	processType			String	Required. The type of change process. Valid values: `change` – The process is a Change Request type.
	aptCommentBox			Object	Contains any comments or files to attach to the change request.
		aptComment		Array	One or more comments about the change request or explanations for the attachments that the user wants to provide.
			commentText	String	The text of the comment. Cannot exceed 5000 characters.
			visibilityType	Enum	Conditionally required to submit the comment. Determines whether process team members from the Partner company associated with the change request can view the comment. Valid values: `ownerOnly` – No, only users from the Owner company can view the comment. `public` – Yes, users from the Partner company associated with the change request can view the comment.
		addAttachment		Array	One or more relevant files to attach to the change request. Supported file formats are DOC, TXT, CSV, JPEG, PNG, and PDF.
			fileName	String	The name of the file to attach. Cannot exceed 255 characters.
			fileSize	String	The size of the file. Cannot exceed 25MB.
			visibilityType	Enum	Conditionally required to submit the attached file. Determines whether process team members from the Partner company associated with the change request can view the attached file. Valid values: `ownerOnly` – No, only users from the Owner company can view the attached file. `public` – Yes, users from the Partner company associated with the change request can view the attached file.
			requestIdentifier	String	The identifier for the upload request provided by File Import and Export Manager.

Example

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
{
    "header": {
        "headerVersion": 1,
        "eventName": "agile-process-teams:add-comment-for-change:v1",
        "ownerId": "fe4c95e5-0f36-4ff7-bb62-4a3449008bd6",
        "processNetworkId": "a70ca41a-ef4d-4b5a-b243-26cff72434ce",
        "appName": "agile-process-teams",
        "dataspace": "default"
    },
    "payload": {
       "id": "4ec1229a-d46f-4fc0-878f-188d318db55a",
       "processType": "change",
       "aptCommentBox":{
        "aptComment":{
            "commentText": "Attaching updated scanner PO per Jen's request",
            "visibilityType": "Public"
        },
        "addAttachment":[
            {
                "fileName" : "INC-4098_shipping-order.pdf",
                "fileSize" : "3mb",
                "visibilityType": "Public",
                "requestIdentifier": "4383a452-1e19-4aa6-98fe-84c9f7a3bd16"
            }
         ]
      }
   }
 }

Add Comment For Change response

Guidelines

Element		Type	Description
header		–	Required. The response header.
	headerVersion	Integer	Required. The version identifier for the response. Valid value is `1`.
	eventName	String	Required. The fully qualified name of the response event. Valid value is `agile-process-teams:add-comment-for-change-response:v1`.
	ownerId	String	Required. The identifier for the Owner company associated with the request.
	isErr	Boolean	Required. Indicates whether the request was successful. Valid values: `true` – The request was successful. `false` – The request was not successful. The errCode field provides error information for troubleshooting.
	errCode	String	Required. The status code of the request. `200_OK` indicates that the request was successful.
	errMsg	String	Conditionally required if the call is unsuccessful. The message associated with the error code.
	licensePlate	String	Required. The unique identifier for the request and response instance.
	exceptionName	String	The exception thrown based on the error code. Valid values: `400 BadRequestException` – The request is missing fields or has invalid data. `404 NotFoundException` – The request is referencing an object that APT cannot find.
payload		–	Required. The payload containing the response body. If the call is unsuccessful, payload is `null`.
	commentId	String	Required. The identifier for the new comment.

Example

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
{
    "header": {
        "headerVersion": 1,
        "eventName": "agile-process-teams:add-comment-for-change-response:v1",
        "ownerId": "94f94f37-2772-4b39-8041-9c2dcfcfff82",
        "isErr": false,
        "errCode": "200_OK",
        "licensePlate": "vXPsFz"
    },
    "payload": {
        "commentId": "a67d7261-33b1-4be6-9760-61ae8fe9eed3"
    }
}

Errors

Element	Error Messages	Description
authorization	User does not have permission to add comments.	The error occurs if the user does not have the Add permission.
id	Process ID is required.	The error occurs if the source is empty or null.
id	[id] does not exist.	The error occurs if the source does not exist in the network.
processType	Process Type is required.	The error occurs if the source is empty or null.
processType	Process Type must be a valid value.	The error occurs if the source does not equal `change`.
aptComment	Comment is greater than max length.	The error occurs if the source exceeds the maximum length of 5000 characters.
aptComment	Comment visibility type must be Public or Internal.	The error occurs if the source is populated and visibilityType does not equal `Public` or `Internal`.
addAttachment	Attachment file size is greater than max size.	The error occurs if the source exceeds the maximum file size of 25MB.
addAttachment	Attachment visibility type must be Public or Internal.	The error occurs if the source is populated and visibilityType does not equal `Public` or `Internal`.

This app also uses standard HTTP response codes. If an error occurs, additional available information regarding the cause of the error is provided in the errMsg element in the relevant response.

Edit Comment For Change

Owners and Partners use this API to modify or remove existing comments and files attached to an change request. Comments and attachments can only be edited by the user that created the comment or attachment.

Upon successful removal, the attachment is marked deleted (isDelete = true) and will display as a deleted comment in the activity history for the change request.

Edit Comment For Change request

Guidelines

Element				Type	Description
header				–	Required. The request header.
	headerVersion			Integer	Required. The version identifier for the request. Valid value is `1`.
	eventName			String	Required. The fully qualified name of the request event. Valid value is `agile-process-teams:edit-comment-for-change:v1`.
	ownerId			String	Required. The identifier for the Owner company associated with the request.
	appName			String	Required. The application that owns the event. Valid value is `agile-process-teams`.
	processNetworkId			String	Required. The network that contains the change request process. This must be a valid network at the Owner company.
	dataspace			String	Required. The dataspace within the environment where the request is being made. Valid value for the Production and Validation environments is `default`.
payload				–	Required. The request body.
	commentId			String	Required. The identifier for the comment to modify.
	processType			String	Required. The type of change process. Valid values: `change` – The process is a Change Request type.
	aptCommentBox			Object	Contains any comments or files to attach to the change request.
		aptComment		Array	One or more comments about the change request or explanations for the attachments that the user wants to provide.
			commentText	String	The text of the comment. Cannot exceed 5000 characters.
			visibilityType	Enum	Conditionally required to submit the comment. Determines whether process team members from the Partner company associated with the change request can view the comment. Valid values: `ownerOnly` – No, only users from the Owner company can view the comment. `public` – Yes, users from the Partner company associated with the change request can view the comment.
		addAttachment		Array	One or more relevant files to attach to the change request. Supported file formats are DOC, TXT, CSV, JPEG, PNG, and PDF.
			fileName	String	The name of the file to attach. Cannot exceed 255 characters.
			fileSize	String	The size of the file. Cannot exceed 25MB.
			visibilityType	Enum	Conditionally required to submit the attached file. Determines whether process team members from the Partner company associated with the change request can view the attached file. Valid values: `ownerOnly` – No, only users from the Owner company can view the attached file. `public` – Yes, users from the Partner company associated with the change request can view the attached file.
			requestIdentifier	String	The identifier for the upload request provided by File Import and Export Manager.
		removeAttachment		Array	One or more existing attachments to remove from the change request.
			attachmentId	String	The identifier for the attachment to remove. The user removing the attachment must be a process team member of the company that originally added the attachment (e.g. a document attached by a Partner company user cannot be removed by an Owner company user).

Example

Edit comment text

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
    "header": {
        "headerVersion": 1,
        "eventName": "agile-process-teams:edit-comment-for-change:v1",
        "ownerId": "94f94f37-2772-4b39-8041-9c2dcfcfff82",
        "processNetworkId": "945feb8e-09a7-4fef-9a8a-b3c5b56f87d",
        "appName": "agile-process-teams",
        "dataspace": "default"
    },
    "payload": {
        "commentId": "a67d7261-33b1-4be6-9760-61ae8fe9eed3",
        "processType": "change",
        "aptCommentBox": {
            "aptComment": {
                "commentText": "Removing incorrect PO document",
                "visibilityType": "Public"
            }
        }
    }
}

Remove attachment

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
    "header": {
        "headerVersion": 1,
        "eventName": "agile-process-teams:edit-comment-for-change:v1",
        "ownerId": "94f94f37-2772-4b39-8041-9c2dcfcfff82",
        "processNetworkId": "945feb8e-09a7-4fef-9a8a-b3c5b56f87d",
        "appName": "agile-process-teams",
        "dataspace": "default"
    },
    "payload": {
        "commentId": "a67d7261-33b1-4be6-9760-61ae8fe9eed3",
        "processType": "change",
        "aptCommentBox": {
            "aptComment": {
                "commentText": "Removing incorrect PO document",
                "visibilityType": "Public"
            },
            "removeAttachment" : [
                "9d84028a-abcd-11eb-90b4-e933a8e8da5e"
            ]
        }
    }
}

Edit Comment For Change response

Guidelines

Element		Type	Description
header		–	Required. The response header.
	headerVersion	Integer	Required. The version identifier for the response. Valid value is `1`.
	eventName	String	Required. The fully qualified name of the response event. Valid value is `agile-process-teams:edit-comment-for-change-response:v1`.
	ownerId	String	Required. The identifier for the Owner company associated with the request.
	isErr	Boolean	Required. Indicates whether the request was successful. Valid values: `true` – The request was successful. `false` – The request was not successful. The errCode field provides error information for troubleshooting.
	errCode	String	Required. The status code of the request. `200_OK` indicates that the request was successful.
	errMsg	String	Conditionally required if the call is unsuccessful. The message associated with the error code.
	licensePlate	String	Required. The unique identifier for the request and response instance.
	exceptionName	String	The exception thrown based on the error code. Valid values: `400 BadRequestException` – The request is missing fields or has invalid data. `404 NotFoundException` – The request is referencing an object that APT cannot find.
payload		–	Required. The payload containing the response body. If the call is unsuccessful, payload is `null`.
	commentId	String	Required. The identifier for the modified comment.

Example

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
{
    "header": {
        "headerVersion": 1,
        "eventName": "agile-process-teams:edit-comment-for-change-response:v1",
        "ownerId": "fe4c95e5-0f36-4ff7-bb62-4a3449008bd6",
        "isErr": false,
        "errCode": "200_OK",
        "licensePlate": "jzC1wS"
    },
    "payload": {
        "commentId": "9d84028a-61ae-11eb-90b4-e933a8e8da5e"
    }
}

Errors

This app uses standard HTTP response codes. If an error occurs, additional available information regarding the cause of the error is provided in the errMsg element in the relevant response.

List Comments For Change

Owners and Partners use this API to return all comments and attachments for a specified change request. Return includes all comments and attachments associated with the change request that the user is authorized to view. Comments and files are listed with additional information (e.g. comment identifier, AWS S3 location of the file), and any deleted items are marked as isDelete = true.

List Comments For Change request

Guidelines

Element		Type	Description
header		–	Required. The request header.
	headerVersion	Integer	Required. The version identifier for the request. Valid value is `1`.
	eventName	String	Required. The fully qualified name of the request event. Valid value is `agile-process-teams:list-comments-for-change:v1`.
	ownerId	String	Required. The identifier for the Owner company associated with the request.
	appName	String	Required. The application that owns the event. Valid value is `agile-process-teams`.
	processNetworkId	String	Required. The network that contains the change request process. This must be a valid network at the Owner company.
	dataspace	String	Required. The dataspace within the environment where the request is being made. Valid value for the Production and Validation environments is `default`.
payload		–	Required. The request body.
	processId	String	Required. The identifier for the change request to return the list of comments for.
	processType	String	Required. The type of change process. Valid values: `change` – The process is a Change Request type.

Example

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
    "header": {
        "headerVersion": 1,
        "eventName": "agile-process-teams:list-comments-for-change:v1",
        "ownerId": "fe4c95e5-0f36-4ff7-bb62-4a3449008bd6",
        "processNetworkId": "a70ca41a-ef4d-4b5a-b243-26cff72434ce",
        "appName": "agile-process-teams",
        "dataspace": "default"
    },
    "payload": {
        "id": "4ec1229a-d46f-4fc0-878f-188d318db55a",
        "processType": "change"
    }
}

List Comments For Change response

Guidelines

Element				Type	Description
header				–	Required. The response header.
	headerVersion			Integer	Required. The version identifier for the response. Valid value is `1`.
	eventName			String	Required. The fully qualified name of the response event. Valid value is `agile-process-teams:list-comments-for-change-response:v1`.
	ownerId			String	Required. The identifier for the Owner company associated with the request.
	isErr			Boolean	Required. Indicates whether the request was successful. Valid values: `true` – The request was successful. `false` – The request was not successful. The errCode field provides error information for troubleshooting.
	errCode			String	Required. The status code of the request. `200_OK` indicates that the request was successful.
	errMsg			String	Conditionally required if the call is unsuccessful. The message associated with the error code.
	licensePlate			String	Required. The unique identifier for the request and response instance.
	exceptionName			String	The exception thrown based on the error code. Valid values: `400 BadRequestException` – The request is missing fields or has invalid data. `404 NotFoundException` – The request is referencing an object that APT cannot find.
payload				–	Required. The payload containing the response body. If the call is unsuccessful, payload is `null`.
	commentsAndAttachments			Object	Contains the list of comments and attachments associated with the change request.
		aptComment		Array	One or more comments about the incident or descriptions of the attachments.
			id	String	The identifier for the comment.
			commentText	String	The text of the comment. Cannot exceed 5000 characters.
			visibilityType	Enum	Conditionally required to submit the comment. Determines whether process team members from the Partner company associated with the change request can view the comment. Valid values: `ownerOnly` – No, only users from the Owner company can view the comment. `public` – Yes, users from the Partner company associated with the change request can view the comment.
		aptAttachments		Array	One or more relevant files to attach to the change request. Supported file formats are DOC, TXT, CSV, JPEG, PNG, and PDF.
			id	String	The identifier for the attached file.
			fileName	String	The name of the file. Cannot exceed 255 characters.
			visibilityType	Enum	Conditionally required to submit the attached file. Determines whether process team members from the Partner company associated with the change request can view the attached file. Valid values: `ownerOnly` – No, only users from the Owner company can view the attached file. `public` – Yes, users from the Partner company associated with the change request can view the attached file.
			fileExtension	String	The file type of the attachment (e.g. jpg, txt).
			isDelete	Boolean	Indicates whether the file is marked as deleted from the change request. Valid values: `true` – Yes, the file is marked as deleted and has been removed from the change request record. `false` – No, the file is not marked as deleted from the change request.
			fileS3Location	String	The AWS S3 location where the file is stored.
			fileSize	String	The size of the file. Cannot exceed 25MB.
			requestIdentifier	String	The identifier for the upload request provided by File Import and Export Manager.

Example

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
{
    "header": {
        "headerVersion": 1,
        "eventName": "agile-process-teams:list-comments-for-change-response:v1",
        "ownerId": "fe4c95e5-0f36-4ff7-bb62-4a3449008bd6",
        "isErr": false,
        "errCode": "200_OK",
        "licensePlate": "t1PCsQ"
    },
    "payload": {
        "commentsAndAttachments": [
            {
                "aptComment": {
                    "id": "3bf5221e-503d-11eb-bcb4-f93431755cb0",
                    "commentText": "My comment",
                    "visibilityType": "Public",
                    "aptAttachments": [
                        {
                            "id": "3c3b2bd0-503d-11eb-bcb4-c78a7a2c7004",
                            "fileName": "fileName",
                            "visibilityType": "Public",
                            "fileExtension": "jpg",
                            "isDelete": false,
                            "fileS3Location": "fileS3Location",
                            "fileSize": "fileSize",
                            "requestIdentifier": "requestIdFromFileManager"
                        }
                    ]
                }
            },
            {
                "aptComment": {
                    "id": "b56fb281-503f-11eb-bcb4-9d4de16ff2a2",
                    "commentText": "My comment2",
                    "visibilityType": "Public",
                    "aptAttachments": [
                        {
                            "id": "b5cacad3-503f-11eb-bcb4-bf0cf8a90d01",
                            "fileName": "fileName",
                            "visibilityType": "Public",
                            "fileExtension": "jpg",
                            "isDelete": false,
                            "fileS3Location": "fileS3Location",
                            "fileSize": "fileSize",
                            "requestIdentifier": "requestIdFromFileManager"
                        }
                    ]
                }
            },
            {
                "aptComment": {
                    "id": "b7c49f06-503f-11eb-bcb4-1dfe60b775fa",
                    "commentText": "My comment3",
                    "visibilityType": "Public",
                    "aptAttachments": [
                        {
                            "id": "b82c1368-503f-11eb-bcb4-adcdbccd111e",
                            "fileName": "fileName",
                            "visibilityType": "Public",
                            "fileExtension": "jpg",
                            "isDelete": false,
                            "fileS3Location": "fileS3Location",
                            "fileSize": "fileSize",
                            "requestIdentifier": "requestIdFromFileManager"
                        }
                    ]
                }
            }
        ]
    }
}

Errors

This app uses standard HTTP response codes. If an error occurs, additional available information regarding the cause of the error is provided in the errMsg element in the relevant response.

Toggle User Follows Change

Owners and Partners use this API to start or stop following a change request. Users that follow a change request receive notifications on updates to the request based on the APT notification settings for their profile. When users stop following the change request, notifications will cease.

Toggle User Follows Change request

Guidelines

Element		Type	Description
header		–	Required. The request header.
	headerVersion	Integer	Required. The version identifier for the request. Valid value is `1`.
	eventName	String	Required. The fully qualified name of the request event. Valid value is `agile-process-teams:toggle-user-follows-change:v1`.
	ownerId	String	Required. The identifier for the Owner company associated with the request.
	appName	String	Required. The application that owns the event. Valid value is `agile-process-teams`.
	processNetworkId	String	Required. The network that contains the change request process. This must be a valid network at the Owner company.
	dataspace	String	Required. The dataspace within the environment where the request is being made. Valid value for the Production and Validation environments is `default`.
payload		–	Required. The request body.
	processId	String	Required.The identifier for the change request to follow or stop following.
	processType	String	Required. The type of change process. Valid values: `change` – The process is a Change Request type.
	follow	Boolean	Required.Indicates whether the user follows the change request and receives notifications based on their profile settings. Valid values: `true` – Yes, the user follows the change request and receives notifications. `false` – No, the user does not follow the change request and does not receive notifications.

Example

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
    "header": {
        "headerVersion": 1,
        "eventName": "agile-process-teams:toggle-user-follows-change:v1",
        "ownerId": "fe4c95e5-0f36-4ff7-bb62-4a3449008bd6",
        "processNetworkId": "a70ca41a-ef4d-4b5a-b243-26cff72434ce",
        "appName": "agile-process-teams",
        "dataspace": "default"
    },
    "payload": {
        "id": "e5701ae7-b447-423a-85c9-b57557fb7007",
        "processType": "change",
        "follow": true
    }
}

Toggle User Follows Change response

Guidelines

Element		Type	Description
header		–	Required. The response header.
	headerVersion	Integer	Required. The version identifier for the response. Valid value is `1`.
	eventName	String	Required. The fully qualified name of the response event. Valid value is `agile-process-teams:toggle-user-follows-change-response:v1`.
	ownerId	String	Required. The identifier for the Owner company associated with the request.
	isErr	Boolean	Required. Indicates whether the request was successful. Valid values: `true` – The request was successful. `false` – The request was not successful. The errCode field provides error information for troubleshooting.
	errCode	String	Required. The status code of the request. `200_OK` indicates that the request was successful.
	errMsg	String	Conditionally required if the call is unsuccessful. The message associated with the error code.
	licensePlate	String	Required. The unique identifier for the request and response instance.
	exceptionName	String	The exception thrown based on the error code. Valid values: `400 BadRequestException` – The request is missing fields or has invalid data. `404 NotFoundException` – The request is referencing an object that APT cannot find.
payload		–	Required. The payload containing the response body. If the call is unsuccessful, payload is `null`.
	id	String	The identifier for the change request.
	message	String	Required. The message indicating whether the user is added or removed as a follower of the specified change request.

Example

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
    "header": {
        "headerVersion": 1,
        "eventName": "agile-process-teams:toggle-user-follows-change-response:v1",
        "ownerId": "fe4c95e5-0f36-4ff7-bb62-4a3449008bd6",
        "isErr": false,
        "errCode": "200_OK",
        "licensePlate": "vXPsFz"
    },
    "payload": {
        "id": "4ec1229a-d46f-4fc0-878f-188d318db55a",
        "successMessage": "User successfully follows change."
    }
}

Errors

Element	Error Messages	Description
authorization	User does not have permission to follow or unfollow the change request.	The error occurs if the user does not have the Read permission.
id	Process ID is required.	The error occurs if the source is empty or null.
id	[id] does not exist.	The error occurs if the source does not exist on the network.
processType	Process Type is required.	The error occurs if the source is empty or null.
processType	Process Type must be a valid value.	The error occurs if the source does not equal `change`.
follow	Follow value is required.	The error occurs if the source is empty or null.
follow	Follow value must either be true or false.	The error occurs if the source does not equal `true` or `false`.
follow	User is already a follower of the Change Request.	The error occurs if the source is `true` and the user already follows the change request.
follow	User does not follow the Change Request.	The error occurs if the source is `false` and the user does not currently follow the change request.

This app uses standard HTTP response codes. If an error occurs, additional available information regarding the cause of the error is provided in the errMsg element in the relevant response.

Get Activity History For Change

Owners and Partners use this API to return the full activity history for a specified change request. The response includes all recorded audit activities and updates to the record.

Get Activity History For Change request

Guidelines

Element		Type	Description
header		–	Required. The request header.
	headerVersion	Integer	Required. The version identifier for the request. Valid value is `1`.
	eventName	String	Required. The fully qualified name of the request event. Valid value is `agile-process-teams:get-activity-history-for-change:v1`.
	ownerId	String	Required. The identifier for the Owner company associated with the request.
	appName	String	Required. The application that owns the event. Valid value is `agile-process-teams`.
	processNetworkId	String	Required. The network that contains the change request process. This must be a valid network at the Owner company.
	dataspace	String	Required. The dataspace within the environment where the request is being made. Valid value for the Production and Validation environments is `default`.
payload		–	Required. The request body.
	processId	String	Required. The identifier for the change request to return the activity history for.
	processType	String	Required. The type of change process. Valid values: `change` – The process is a Change Request type.

Example

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
    "header": {
        "headerVersion": 1,
        "eventName": "agile-process-teams:get-activity-history-for-change:v1",
        "ownerId": "tracelink",
        "processNetworkId": "a70ca41a-ef4d-4b5a-b243-26cff72434ce",
        "appName": "agile-process-teams",
        "dataspace": "default"
    },
    "payload": {
        "id": "4ec1229a-d46f-4fc0-878f-188d318db55a",
        "processType": "change"
    }
}

Get Activity History For Change response

Guidelines

Element					Type	Description
header					–	Required. The response header.
	headerVersion				Integer	Required. The version identifier for the response. Valid value is `1`.
	eventName				String	Required. The fully qualified name of the response event. Valid value is `agile-process-teams:get-activity-history-for-change-response:v1`.
	ownerId				String	Required. The identifier for the Owner company associated with the request.
	isErr				Boolean	Required. Indicates whether the request was successful. Valid values: `true` – The request was successful. `false` – The request was not successful. The errCode field provides error information for troubleshooting.
	errCode				String	Required. The status code of the request. `200_OK` indicates that the request was successful.
	errMsg				String	Conditionally required if the call is unsuccessful. The message associated with the error code.
	licensePlate				String	Required. The unique identifier for the request and response instance.
	exceptionName				String	The exception thrown based on the error code. Valid values: `400 BadRequestException` – The request is missing fields or has invalid data. `404 NotFoundException` – The request is referencing an object that APT cannot find.
payload					–	Required. The payload containing the response body. If the call is unsuccessful, payload is `null`.
	auditTrailRecordList				Array	Required. Array of audit trail records for the change request.
		auditChangeEntry			–	Required. The identifier for the audit entry.
			auditChangeDetail		–	Required. Contains information about the audit entry.
				auditRecordDisplayName	String	Required. The name for the audit record.
				auditRecordNewValue	String	Required. Updated value of the audit record.
				auditRecordOldValue	String	Required. Previous value of the audit record.
				auditRecordNewResolvedId	String	Conditionally required if the updated attribute is a foreign key. The updated attribute value related to the audit record.
		timeStamp			Integer	Required. Date and time of the audit entry.
		networkNodeId			String	Required. The identifier of the Owner company network that owns the data.
		companyName			String	Required. The name of the company that owns the data.
		performedByUserName			String	The name of the user that made the change.
		performedByCompanyName			String	Required. Name of the company that made the change for that audit entry
		auditItemIdentifier			String	Required. The identifier for the audit item.
		applicationName			String	Required. The name of the application that the event occurred within.
		actionType			String	Required. Represents the type of change the user performed (e.g. CREATE, MODIFY, DELETE, OTHER).
		businessObjectName			String	Required. The object of the application that the event occurred within.
		businessObjectSchemaName			String	Required. The specific object within the businessObjectName that the user updated
		supportAccessUserName			String	The email address of the TraceLink Support Representative performing an action on behalf of the user specified in the performedByUserName field.

Example

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
{
    "header": {
        "headerVersion": 1,
        "eventName": "agile-process-teams:get-activity-history-for-change-response:v1",
        "ownerId": "0e093b3c-ad28-48ab-97a9-fac574c1cce8",
        "isErr": false,
        "errCode": "200_OK",
        "licensePlate": "NVd76b"
    },
    "payload": {
        "auditTrailRecordList": [
            {
                "auditChangeEntry": {
                    "auditChangeDetail": [
                        {
                            "auditRecordDisplayName": "apt Business Object Summary",
                            "auditRecordNewValue": "AGGREGATION_ERROR"
                        },
                        {
                            "auditRecordDisplayName": "Business Priority",
                            "auditRecordNewValue": "HIGH"
                        },
                        {
                            "auditRecordDisplayName": "Apt Business Object ID",
                            "auditRecordNewValue": "TLNK-1234"
                        },
                        {
                            "auditRecordNewResolvedId": "015c9f20-731a-4e1c-8a25-634edc07c134",
                            "auditRecordDisplayName": "APT Business Object Assigned To Company Partner Master Data",
                            "auditRecordNewValue": "Kendall"
                        }
                    ]
                },
                "supportAccessUserName": "",
                "companyName": "Kendall Pharma",
                "businessObjectName": "Incident",
                "performedByCompanyName": "Kendall Pharma",
                "supportAccessUserId": "",
                "timeStamp": 1612384626000,
                "performedByNetworkNodeId": "00448f53-fc7f-489a-a847-dbdb083cb646",
                "actionType": "Added",
                "networkNodeId": "00448f53-fc7f-489a-a847-dbdb083cb646",
                "businessObjectId": "53a671d1-af5e-4e5b-b10a-c8db389f82ca",
                "auditItemIdentifier": "TLNK-1234",
                "businessObjectSchemaName": "agile-process-teams:incident:v1",
                "performedByUserName": "Evelyn Rose",
                "performedByUserId": "007bee3d-ba11-47d1-8b0c-68bba8f591cb",
                "applicationName": "Agile Process Teams"
            }
        ]
    }
}

Errors

This app uses standard HTTP response codes. If an error occurs, additional available information regarding the cause of the error is provided in the errMsg element in the relevant response.