XOG: Matrix

ccppmop1561
Use the matrix XOG object to view inbound and outbound cost/rate matrix instances. Rate matrices give you flexibility in defining cost for particular services or resources.
2
Rate Matrix XOG Updates
To update a rate matrix using XOG, unless you use the new incremental flag, include 
all
 the rows in the matrix in the XOG input file. The rows in the matrix do not include unique IDs for each row. The update causes a full replace of all rows in the matrix. If you do not include all the matrix rows in the XOG input file, the update removes the existing rows from the matrix and adds only the new rows.
We recommend that you complete the following steps to update an existing rate matrix:
  1. Perform a XOG read action to create an output file of all the existing rows in the rate matrix.
  2. Update the output file to include any additional rows that you want to add.
  3. Perform the XOG write action to update the matrix.
nikuxog_matrix.xsd Schema
Read and Write XML Files
The following XML files are included:
  • matrices_read.xml. Use this file to export matrices from 
    Clarity PPM
    .
  • matrices_write.xml. Use this file to import matrices that were previously exported from 
    Clarity PPM
    .
Filters
The following explicit read filters are used:
  • name
    The name of the matrix.
  • type
    The type of the matrix (Cost or Rate).
  • location
    The location of the matrix.
Error Handling
The following errors can be thrown when importing or exporting the cost plan:
  • Failed to export matrices.
  • Failed to import matrices.
Schema Mappings
Mappings for the schema tags are provided.
columnType Schema Tag
This tag is part of the schema mapping for the matrix XOG object. The columns that you assign to a matrix through the XOG are saved to the PPA_MATRIXCOLDEF table.
This tag has the following attribute:
  • name
    Optional. Defines the list of columns to be added to the matrix rows and has the following attributes:
    • chargeCode
      Defines the charge code for the matrix column.
      Table and Column:
      PPA_MATRIXCOLDEF.FIELDNAME
      Type:
      String
    • clntclass
      Optional. Defines the client class for the matrix column.
      Table and Column:
      PPA_MATRIXCOLDEF.FIELDNAME
      Type:
      String
    • company_code
      Defines the company code for the matrix row.
      Table and Column:
      PPA_MATRIXCOLDEF.FIELDNAME
      Type:
      String
    • departcode
      Defines the department code for the matrix column.
      Table and Column:
      PPA_MATRIXCOLDEF.FIELDNAME
      Type:
      String
    • entity
      Defines the entity for the matrix column.
      Table and Column:
      PPA_MATRIXCOLDEF.FIELDNAME
      Type:
      String
    • inputtype
      Defines the input type code for the matrix column.
      Table and Column:
      PPA_MATRIXCOLDEF.FIELDNAME
      Type:
      String
    • locationid
      Defines the location unique identifier for the matrix column.
      Table and Column:
      PPA_MATRIXCOLDEF.FIELDNAME
      Type:
      String
    • projclass
      Defines the project class for the matrix column.
      Table and Column:
      PPA_MATRIXCOLDEF.FIELDNAME
      Type:
      String
    • project_code
      Defines the project code for the matrix column.
      Table and Column:
      PPA_MATRIXCOLDEF.FIELDNAME
      Type:
      String
    • resourceClass
      Defines the resource class for the matrix column.
      Table and Column:
      PPA_MATRIXCOLDEF.FIELDNAME
      Type:
      String
    • resource_code
      Defines the resource code for the matrix column.
      Table and Column:
      PPA_MATRIXCOLDEF.FIELDNAME
      Type:
      String
    • resourceRole
      Optional. Defines the resource role for the matrix column.
      Table and Column:
      PPA_MATRIXCOLDEF.FIELDNAME
      Type:
      String
    • transactionClass
      Optional. Defines the transaction class for the matrix column.
      Table and Column:
      PPA_MATRIXCOLDEF.FIELDNAME
      Type:
      String
    • projsitecode
      Defines the project site code for the matrix column.
      Table and Column:
      PPA_MATRIXCOLDEF.FIELDNAME
      Type:
      String
MatrixRowType Schema Tag
The MatrixRowType tag is part of the schema mapping for the matrix XOG object. The values for the rows you add to the matrix are saved to a column in the PPA_MATRIXVALUES table.
 A specific attribute is not tied to a specific ordered value ( VALUE1, VALUE2, and so on) in the matrix. You can configure the columns in a matrix in any order. For example, you can configure a matrix with columns for Resource, Role, Charge Code, and Transaction Class. In this case, the respective attribute data is stored in VALUE1, VALUE2, VALUE3, and VALUE4 for the matrix rows. If you do not define additional columns, the other value fields are not used for that matrix.
This tag has the following attributes:
  • fromDate
    Optional. Defines the date from which to apply the matrix row.
    Table and Column:
    PPA_MATRIXVALUES.FROMDATE
    Type:
    Date
  • toDate
    Optional. Defines the date until which to apply the matrix row.
    Table and Column:
    PPA_MATRIXVALUES.TODATE
    Type:
    Date
  • chargecode
    Optional. Defines the chargecode for the matrix row.
    Table and Column:
    PPA_MATRIXVALUES.VALUE1
    Type:
    String
  • Department
    Optional. Defines the department for the matrix row.
    Table and Column:
    PPA_MATRIXVALUES.VALUE2
    Type:
    String
  • entity
    Optional. Defines the entity for the matrix row.
    Table and Column:
    PPA_MATRIXVALUES.VALUE3
    Type:
    String
  • Input type code
    Optional. Defines the input type code for the matrix row.
    Table and Column:
    PPA_MATRIXVALUES.VALUE6
    Type:
    String
  • location
    Optional. Defines the location for the matrix row.
    Table and Column:
    PPA_MATRIXVALUES.VALUE9
    Type:
    String
  • Project class
    Optional. Defines the project class for the matrix row.
    Table and Column:
    PPA_MATRIXVALUES.VALUE8
    Type:
    String
  • Project
    Optional. Defines the project for the matrix row.
    Table and Column:
    PPA_MATRIXVALUES.VALUE7
    Type:
    String
  • Resource class
    Optional. Defines the resource class for the matrix row.
    Table and Column:
    PPA_MATRIXVALUES.VALUE9
    Type:
    String
  • Resource
    Optional. Defines the resource or team for the matrix row.
    Table and Column:
    PPA_MATRIXVALUES.VALUE10
    Type:
    String
  • rate
    Optional. Defines the rate for the matrix row.
    Table and Column:
    PPA_MATRIXVALUES.NUMVAL1
    Type:
    Double
  • standardCost
    Optional. Defines the standard cost for the matrix row.
    Table and Column:
    PPA_MATRIXVALUES.NUMVAL2
    Type:
    Double
  • actualCost
    Optional. Defines the actual cost for the matrix row.
    Table and Column:
    PPA_MATRIXVALUES.NUMVAL3
    Type:
    Double
  • currencyCode
    Optional. Defines the currency code for the matrix row.
    Table and Column:
    PPA_MATRIXVALUES.MATRIX_CURRENCY_CODE
    Type:
    String
  • typeCode
    Optional. Defines the cost plus code for the matrix row.
    Table and Column:
    PPA_MATRIXVALUES.STRVAL1
    Type:
    String
Incremental Rate Matrix Attribute
CA PPM 15.4 introduced a new
incremental
attribute that makes it easier to keep your rate matrix up-to-date at your organization. As an administrator or content developer, you can perform an incremental update or insert to the rate matrix using XOG.
In previous releases, the rate matrix XOG required sending the entire list of rate matrix rows for all matrix columns. To change or add a single rate matrix row, you had to replace the entire list including the past history. Out-of-memory exception errors might occur due to the large size of the XML or the quantity of rate matrix rows in the system. In very large CA PPM deployments, you might have used stored procedures or direct insert and update statements.
Rate matrix XOG functionality is enhanced to allow you to specify only an incremental subset of selected rows for insert or update.
  • This enhancement supports any previous functionality you already had in place. For example, you can continue to use a legacy process with stored procedures for rate matrix integration.
  • The new incremental flag indicates that you want to use the new functionality. Use this setting for incremental inserts of new matrix rows or updates to existing rows instead of replacing the entire rate matrix.
  • You can apply the flag at the rate matrix level in the same XOG file.
You can import one rate matrix with the flag while importing another rate matrix in the same XOG file without the flag.
  • If your XML content does not include the incremental element, the XOG functionality remains as it was before (full replacement). The full replacement behavior also occurs if your matrix XML header contains incremental = false.
  • If your XML content includes incremental = true, the new insert or update operation occurs on the partial rows. The system uses the existing matrix column configuration.
  • If no rate matrix exists, the XOG operation creates a new matrix.
The system determines the uniqueness of each rate matrix row. The system checks existing matrix rows for the following data: the From Date plus the selected columns configured in the rate matrix. You can configure each matrix with up to ten optional columns.
  • If the system finds an existing matrix row, it updates the static fields on the record.
  • If the system does not find an existing matrix row, it inserts a new matrix row.
The system continues to use existing static messages and error codes upon completion of XOG actions. For overlapping data ranges, the system also performs all existing validations as it did in previous releases.
When the incremental attribute is
true
, the system updates existing records with the following information:
  • Actual Cost
  • Standard Cost
  • Rate
  • To Date
  • Currency
  • Cost Plus Code
You are not required to replace the entire list.
Incremental Rate Matrix XOG File Examples
Example 1
: In this case, we set the flag to
true
. If we need to add a new row or update an existing row, we can import only those rows.
<?xml version="1.0" encoding="UTF-8"?> <NikuDataBus xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../xsd/nikuxog_matrix.xsd"> <Header action="write" externalSource="NIKU" objectType="matrix" version="12.1.1.1047"/> <matrices> <matrix defaultCurrencyCode="USD" name="RMEXYZLaborMatrix" incremental="true" notes="RMEXYZLaborMatrix" type="Cost/Rate"> <columns> <column name="chargeCode"/> </columns> <matrixRows> <matrixRow actualCost="1" chargeCode="*" currencyCode="USD" fromDate="1990-01-01" rate="5" standardCost="3" toDate="2017-12-31"/> <matrixRow actualCost="1" chargeCode="rmexyz00002" currencyCode="USD" fromDate="1990-01-01" rate="18" standardCost="3" toDate="2017-12-31"/> </matrixRows> </matrix> </matrices> </NikuDataBus>
Example 2
: In this case, we also set the flag to
true
. This file inserts the new matrix row with rmexyz00001 and also modifies the row with charge code rmexyz00002. The row with chargeCode="*" remains unchanged.
<?xml version="1.0" encoding="UTF-8"?> <NikuDataBus xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../xsd/nikuxog_matrix.xsd"> <Header action="write" externalSource="NIKU" objectType="matrix" version="12.1.1.1047"/> <matrices> <matrix defaultCurrencyCode="USD" name="RMEXYZLaborMatrix" incremental="true" notes="RMEXYZLaborMatrix" type="Cost/Rate"> <columns> <column name="chargeCode"/> </columns> <matrixRows> <matrixRow actualCost="2" chargeCode="rmexyz00002" currencyCode="USD" fromDate="1990-01-01" rate="28" standardCost="13" toDate="2017-12-31"/> <matrixRow actualCost="11" chargeCode="rmexyz00001" currencyCode="USD" fromDate="1990-01-01" rate="7" standardCost="22" toDate="2017-01-31"/> </matrixRows> </matrix> </matrices> </NikuDataBus>