Create, update and delete CA through API

A Cost Allocation Setup consists of four key components:

1. Sets: The overarching name and ID of the cost allocation (CA).
2. Steps: These are the definitions of steps or "questions" used in the CA.
3. StepTypes: Categories or values for the steps, such as Project, Component, or Machine.
4. Values: Specific values assigned to each step.

All these components work together to create a comprehensive cost allocation system.

Step 1: Create the Structure

Important Note: It is recommended to create the Sets, Steps, and StepTypes manually in the admin portal. Avoid using the API for the initial structure to reduce errors. If you've done that move on to Step 5 of this guide.

Step 2: Create a Set

The Set serves as the foundation of the cost allocation structure.

API Endpoint:
POST https://api.cribwise.com/integration/v1/integrationapi/CostAllocationSets

Payload:

{
  "externalId": "CATree",
  "name": "CATree"
}

Step 3: Create a StepType

StepTypes define custom categories or values for your steps.

API Endpoint:
POST https://api.cribwise.com/integration/v1/integrationapi/CostAllocationStepTypes

Payload:

{
  "name": "Project"
}

To retrieve existing StepTypes for use in Steps:
GET https://api.cribwise.com/integration/v1/integrationapi/CostAllocationStepTypes

Example Result:

{
  "name": "Component",
  "isFixed": true,
  "id": "Default.Stock.CostAllocationLevelType2788",
  "version": 1,
  "lastModified": "2022-03-23T08:16:04.6620766+00:00"
}

Step 4: Create a Step

Steps link StepTypes to a specific Set and can include additional properties like validation and hierarchy.

API Endpoint:
POST https://api.cribwise.com/integration/v1/integrationapi/CostAllocationSteps

Payload:

{
  "stepTypeId": "Default.Stock.CostAllocationLevelType2788",
  "setId": "Stock.CostAllocationSet3286",
  "isRequired": true,
  "isValidated": true,
  "type": "Hierarchy",
  "allowedValues": []
}

Step 5: Add Values

Each Step has its own values, which represent specific options within that step.

1. Retrieve Steps:
   GET https://api.cribwise.com/integration/v1/integrationapi/CostAllocationSteps

   Match the returned StepID with its corresponding StepTypeID to verify its name: GET https://api.cribwise.com/integration/v1/integrationapi/CostAllocationStepTypes

2. Add a Value to a Step:
   API Endpoint:
   POST https://api.cribwise.com/integration/v1/integrationapi/CostAllocationValues

   Payload:

   {
     "value": "Comp1",
     "stepId": "Stock.CostAllocationLevel6627"
   }
   

3. Repeat this process for all remaining values in the step.

Step 6: Create the Hierarchy

To establish relationships between values, you need to define a hierarchy.

1. Retrieve Existing Values:
   GET https://api.cribwise.com/integration/v1/integrationapi/CostAllocationValues

   Example Result:

    

   {
     "value": "Comp1",
     "isActive": true,
     "stepId": "Stock.CostAllocationLevel6627",
     "allowCustomValue": false,
     "id": "Stock.CostAllocationDefinition191659",
     "version": 1,
     "lastModified": "2024-10-16T19:05:13.8812841+00:00"
   }
   

2. Assign Values to Hierarchy:
   Use the retrieved valueId and, if applicable, a parentId to define the hierarchy.

   API Endpoint:
   POST https://api.cribwise.com/integration/v1/integrationapi/CostAllocationHierarchyInstances

   Payload:

    

     {
       "valueId": "Stock.CostAllocationDefinition191659"
     },
     {
       "parentId": "Stock.CostAllocationInstance2944462",
       "valueId": "Stock.CostAllocationDefinition191662"
     },
     {
       "parentId": "Stock.CostAllocationInstance2944465",
       "valueId": "Stock.CostAllocationDefinition191666"
     } 

3. Iterate the Hierarchy:
   After adding a value, use:
   GET https://api.cribwise.com/integration/v1/integrationapi/CostAllocationHierarchyInstances
   to retrieve the updated hierarchy and use the parentId for subsequent additions.

Step 7: Create Hierarchy Restrictions (Relations)

To further refine your Cost Allocation setup, you can create restrictions that specify which items, users, or user groups are associated with a particular Cost Allocation path.

Assign Items to a CA Path

This step links specific items to a Cost Allocation path.

1. Find the Item ID:
   Use the following API to retrieve the list of items and find the desired itemId:

    

   GET https://api.cribwise.com/integration/v1/integrationapi/Items

   Example Result:

    

   {
     "id": "Stock.Item1216756",
     "name": "Example Item",
     "externalId": "EXT12345",
     "category": "Tools",
     "lastModified": "2024-10-16T19:05:13.8812841+00:00"
   }
   

2. Link Item to Cost Allocation Instance: Use the following API to assign an item to a specific Cost Allocation path:

    

   POST https://api.cribwise.com/integration/v1/integrationapi/CostAllocationInstanceItemRelations

   Payload:

    

   {
     "itemId": "Stock.Item1216756",
     "instanceId": "Stock.CostAllocationInstance2944473"
   }
   

   This creates a relation between the item and the specific Cost Allocation instance.

Assign Users and User Groups

Similarly, you can create restrictions for users or user groups.

1. Find User or User Group IDs:
   Use APIs to retrieve user or user group IDs:

   • Users: GET https://api.cribwise.com/integration/v1/integrationapi/Users
   • User Groups:GET https://api.cribwise.com/integration/v1/integrationapi/UserGroups

2. Create Relations for Users/User Groups: Use the same API endpoint:

    

   POST https://api.cribwise.com/integration/v1/integrationapi/CostAllocationInstanceItemRelations

   Payload Example (User):

    

   {
     "userId": "User12345",
     "instanceId": "Stock.CostAllocationInstance2944473"
   }
   

   Payload Example (User Group):

    

   {
     "userGroupId": "Group67890",
     "instanceId": "Stock.CostAllocationInstance2944473"
   }
   

Additional Notes

• Hierarchy Types: Ensure the StepType is of type "Hierarchy" for hierarchical relationships. If it is "List", you only need to add values without hierarchy definitions.
• Admin Portal: Use the admin portal for creating and managing Sets, Steps, and StepTypes to simplify the process and minimize API errors.