Error creating artifacts via WSAPI due to incorrect JSON reference formatting - Rally

Products

• Rally SaaS

Issue/Introduction

When using the Rally Web Services API (WSAPI) to create or update artifacts such as User Stories (HierarchicalRequirement), Tasks, or Defects, the request may fail if reference fields are not formatted correctly. This article provides the required JSON structure for reference fields like Project, Owner, and Tags.

Symptoms

• API requests return success but no object is created.
• API returns errors indicating that required fields are missing or invalid.
• Objects are created but missing values in reference fields (Project, Workspace, Owner).

Cause

In the Rally WSAPI, reference fields (fields that link to other objects) must be passed as a JSON object containing a _ref key. Passing the reference as a simple string path (e.g., "Project": "/project/####") is invalid and will cause the field to be ignored or the request to fail.

Resolution

Ensure all reference fields in the JSON payload use the _ref object structure.

Correct JSON Payload Example

Use the following structure when creating a HierarchicalRequirement (User Story):

json

 

{  "HierarchicalRequirement": {    "Name": "Sample User Story",    "Description": "Detailed description here",    "Project": {      "_ref": "/project/####"    },    "Owner": {      "_ref": "/user/####"    },    "ScheduleState": "Defined",    "PlanEstimate": 5,    "Tags": [      {        "_ref": "/tag/####"      }    ]  }}

Verification Steps

1. Verify the endpoint URL is correct for the object type (e.g., https://rally1.rallydev.com/slm/webservice/v2.0/hierarchicalrequirement/create).
2. Use a POST request for creation.
3. Check the API response body for an "Errors" or "Warnings" array to identify specific field failures.

Additional Information

• Find the ObjectID (OID) of Projects, Workspaces, Timeboxes and Artifacts
• To speak with a customer representative or a Support Engineer see Contact Support. Scroll to the bottom of the page and click on your respective region.