Adaptive Planning 函數

測試連線函數

環境定義參數

測試連線附帶 1 個參數「context」。

方法	參數	傳回類型	說明
getDataSource()		ai.dataSource	傳回作用中的資料來源。
getCalendar()		ai.calendar	傳回 Adaptive Planning 行事歷

範例

function testConnection(context) {
    // Step 1: Create a https request to send to Earthquake USGS API
    var url = 'https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/all_hour.atom';
    var method = 'GET';
    var body = ``;
    var headers = {};
    // Step 2: Send request and receive response
    try{
    
        var response = ai.https.request(url, method, body, headers);
        ai.log.logInfo("Test Connection Successful");
       }
    catch(e)
    {
    
        ai.log.logInfo("Test Connection Failed");
    }
    // Step 3: Interrogate response to see if it was successful. Return true or false depending on the result.
    if (response.getHttpCode() == '200') {
        var body = response.getBody();
        return true;
    } else {
        return false;
    }
}

匯入結構函數

環境定義參數

匯入結構函數隨附 1 個參數「context」。

方法	參數	傳回類型	說明
getDataSource()		ai.dataSource	傳回作用中的資料來源。
getProgressManager()		ai.progressManager	傳回可用於更新「匯入結構」任務完成百分比值的物件。
getStructureBuilder()		ai.structure.structureBuilder	傳回用於建立資料來源結構 - 表格、欄、參數等的物件。
getCalendar()		ai.calendar	傳回 Adaptive Planning 行事歷

範例

function importStructure(context) {
    //getDataSource
    var dataSource=context.getDataSource();
    // getStructureBuilder
    var builder = context.getStructureBuilder();
    //getCalendar
    var calendar= context.getCalendar();
  }

ai.progressManager

ai.progressManager 物件可讓使用者手動設定正在執行「匯入結構」指令碼的任務完成百分比。指令碼執行佔整體任務完成百分比的 70%。因此，透過 ai.progressManager 定義的進度值會進行縮放，以代表整體任務的進度。範例︰將 ai.progressManager 的完成百分比設為 100% 將等於執行中任務的 70%，50% 等於執行中任務的 35%，依此類推。

函數

方法	參數	傳回類型	說明
getProgress()		數字	傳回使用者所定義的指令碼完成百分比。如果使用者先前未設定完成百分比，則此函數會傳回 0。
setProgress( 值 )	value︰要設定指令碼完成百分比的目標數值		設定指令碼完成百分比。其運作方式如下︰ 僅接受數值，例如 0、10、22.5、100、110。 大於 100 的值會被視為 100。 小於目前指令碼進度的值會被忽略。範例︰先呼叫 setProgress(50)，再呼叫 setProgress(40)。這會使指令碼完成百分比達到 50%。 「值」的所有其他輸入類型都不會影響指令碼進度，

範例

function importStructure(context) {    
    ..........
 
 
    var progressManager = context.getProgressManager();
 
 
    // Set script progress % to 10
    progressManager.setProgress(10);
 
 
    // Increase script progress % to 50
    progressManager.setProgress(50.0);
 
 
    // Set progress to 100 by using value greater than 100
    progressManager.setProgress(230);
    progressManager.getProgress(); // returns 100
 
 
    // Increase progress by 10% based on current progress
    progressManager.setProgress(progressManager.getProgress() + 10);
 
 
 
 
    ..........
    return builder;
 }

ai.structure.structureBuilder

函數

方法	參數	退貨	說明
addTable(tableId)	tableId : String 表格的唯一 ID	ai.structure.editableTable	為資料來源建立並傳回新表格。

範例

提供定義將由資料填入的表格和欄結構的功能。

function importStructure(context) {
........
//getStructureBuilder
    var builder = context.getStructureBuilder();
//Example addTable( tableId )-"Sample"
    var table = builder.addTable("Sample");
....... 
}

ai.structure.editableTable

函數

方法	參數	退貨	說明
setDisplayName( displayName )	displayName : 要將表格的顯示名稱屬性設定為的字串值。	ai.structure.editableTable	設定表格的顯示名稱。
addColumn( columnId )	columnId : 欄的字串 RemoteId	ai.structure.editableColumn	建立並傳回表格的新子系欄。
addRequiredParameter(parameterId)	參數 ID ︰參數的字串 ID	ai.structure.editableParameter	建立並傳回表格的新必要參數。當此表格做為 ImportData 或 ImportStructure 的一部分時，必須將可指派參數設定為必填參數的值。

ai.structure.editableColumn

函數

方法	參數	退貨	說明
setDisplayName( value )	value : 要將欄的 displayName 屬性設定為的字串值	ai.structure.editableColumn	設定欄的顯示名稱。
setDisplayOrder( value )	value ︰String 要將欄的 displayOrder 屬性設定為的值	ai.structure.editableColumn	設定欄的顯示順序。
setIncludeByDefault( value )	value ︰要將欄設為 IsEnabled 屬性的布林值	ai.structure.editableColumn	設定要啟用資料匯入的欄。
setIncludeInKey( value )	value ︰布林值，要將欄的 includeInKey 屬性設定為	ai.structure.editableColumn	指出欄是否是表格索引鍵的一部分。
setMandatoryForImports( value )	value ︰布林值，指出此欄是否已啟用依據必填項目匯入資料的功能	ai.structure.editableColumn	設定要啟用資料匯入的欄，截止日期為必填。
setNonFilterable( value )	value ︰要將欄的 nonFilterable 屬性設定為的布林值	ai.structure.editableColumn	指出該欄是否可包含在遠端查詢中。
setRemoteColumnType( value )	value : 要將欄的 remoteColumnType 屬性設定為的字串值	ai.structure.editableColumn	設定欄的遠端資料類型，例如「字串」、「整數」等
setTextColumnType(length)	length : Integer 此欄可容納值的最大長度	ai.structure.editableColumn	將該欄設為文字欄。
setIntegerColumnType()		ai.structure.editableColumn	將欄設為整數欄。
setFloatColumnType()		ai.structure.editableColumn	將欄設為雙精度欄。
setBooleanColumnType()		ai.structure.editableColumn	將欄設為布林值欄。
setDateTimeColumnType()		ai.structure.editableColumn	將此欄設為日期時間欄。

ai.structure.editableParameter

函數

方法	參數	退貨	說明
setDisplayName( value )	value ︰String 值，要將參數的 displayName 屬性設定為		設定參數的顯示名稱。
setForDataImport( value )	value ︰布林值，該值指出參數是否可在 ImportData 指令碼中存取		啟用參數以匯入資料。
setTypePeriodRange()			將參數類型變更為「期間範圍」

範例

function importStructure(context) {
...............
    //addColumn
    var valueColumn= table.addColumn('Value');
    //setDisplayName
    valueColumn.setDisplayName('Value');
    // Set the data type for the column - Can be Integer, Float, DateTime or Boolean values
    valueColumn.setFloatColumnType();
    //setDisplayOrder
    valueColumn.setDisplayOrder('0');
    //setIncludeByDefault
    valueColumn.setIncludeByDefault(true);
    //setRemoteColumnType
    valueColumn.setRemoteColumnType('float');
    // setIncludeInKey
    valueColumn.setIncludeInKey(false);
    //setMandatoryForImports
     valueColumn.setMandatoryForImports(false);
..............
}

匯入資料函數

環境定義參數

匯入資料函數隨附 1 個參數「context」。

方法	參數	傳回類型	說明
getRowset() 在 2021R1 版本中，支援人員應您的要求啟用 getRowset(ColumnIds) 後，會在記錄中產生 API 棄用警告。getRowset() 方法將繼續運作，但會忽略任何參數。		ai.rowset	傳回要新增列的 Rowset 物件。列集定義了表格、欄和 MaxRows。
getRowset([columnIds]) 在 Workday Customer Center 建立個案，以啟用「 自訂雲端服務依指定欄讀取階段處理表 」功能標幟。	[欄 ID]	ai.rowset	以您指定的欄順序傳回要新增列的列集物件。列集定義了表格、欄和 MaxRows。
getDataSource()		ai.dataSource	傳回作用中的資料來源。
getCalendar()		ai.calendar	傳回 Adaptive Planning 行事歷

範例

此範例假設列集依序包含整數欄和文字欄。

function importData(context) {
...........
   var rowset = context.getRowset();
..........
    var rowset= context.getRowset([ 'NAME', 'ID']);
}

ai.rowset

列集物件是將使用者指令碼內的「列」傳輸至整合堆棧的機制。列集會為使用者針對其執行 PreviewData 或 ImportData 指令碼的表格形狀 (欄名稱及其資料類型、maxRows 和 tableId) 建立模型。

函數

方法	參數	傳回類型	說明
addRow( cells )	cells : Array<Primitive Types> 每欄的值陣列 (依序排列)		將儲存格值的陣列以列的形式新增至「列集」。儲存格值必須是有效的字串 (可以為空值)、數字 (整數或小數)、布林值或日期物件。每個儲存格值類型都必須符合其對應欄的資料類型，順序由 getColumnNames 定義。儲存格值的數目必須與定義的欄數相符。
getTableId()		String	傳回正在預覽的表格的表格 ID。
getMaxRows()		整數	傳回此列集中允許的列數上限。0 表示不明，與 ImportData 使用的一樣。
getColumns()		Array<ai.dataSource.table.column>	傳回為預覽選取的表格欄。
setSmartParsingEnabled(val)	val ︰布林值，指出是開啟還是關閉此功能		如果可能，啟用此設定會在執行addRow() 函數期間，自動將每個字串儲存格值剖析為目標欄的必要資料類型。如果目前儲存格值的資料類型與目標欄的資料類型不相符，使用者就不必查詢目標欄的資料類型並進行手動剖析。這在處理第 3 方 API 時尤其有用，這些 API 會透過 JSON 或 XML 將所有列值以字串的形式傳回，且每個儲存格值都可成功剖析為整數、浮點數、布林或 DateTime 值。
getSmartParsingEnabled()		Boolean	如果已啟用此設定，則傳回 True。預設為 False。

function importData(context) {
    var dataSource = context.getDataSource();
    var settings = dataSource.getSettings();
    var rowset = context.getRowset();
    
    //Set and Get SmartParsingEnabled() value
    rowset.setSmartParsingEnabled(true);
    ai.log.logInfo(getSmartParsingEnabled()); //true
    
    //Set a Start date and End date in the Designer Settings tab with the name "Period Range"
    var startDateString = dataSource.getSetting("Period Range").getValue().getFromPeriodStartDateTime().substring(0, 10);
    var endDateString = dataSource.getSetting("Period Range").getValue().getToPeriodEndDateTime().substring(0, 10);
    
    //get columns
    var columns = rowset.getColumns();

    for (var i = 0; i < dataSample.rows.length; i++) {
        var colName;
        var cells = [];
        for (var j = 0; j < columns.length; j++) {
            var colValue;
            var re = /\\\-/g;
            if ((new Date(dataSample.rows[i]["Effective Date"]) >= new Date(startDateString)) && (new Date(dataSample.rows[i]["Effective Date"]) < new Date(endDateString))) {
                colName = columns[j].getId();
                colValue = dataSample.rows[i][colName];
                cells.push(colValue.toString().replace(re, '.'));

            }
        }
        if (cells.length == columns.length) {
            //add rows
            rowset.addRow(cells);
        }
    }
}  

預覽資料功能

環境定義參數

預覽資料函數隨附 1 個參數「context」。

方法	參數	傳回類型	說明
getDataSource()		ai.dataSource	傳回作用中的資料來源。
getRowset()		ai.rowset	傳回要新增列的 Rowset 物件。列集定義了表格、欄和 MaxRows。
getCalendar()		ai.calendar	傳回 Adaptive Planning 行事歷

範例

提供預覽儲存在雲端來源中的資料的功能。

function previewData(context) {

    var dataSource = context.getDataSource();
    var settings = dataSource.getSettings();
    var rowset = context.getRowset();
    
    //Set and Get SmartParsingEnabled() value
    rowset.setSmartParsingEnabled(true);
    ai.log.logInfo(getSmartParsingEnabled()); //true
    
    //Set a Start date and End date in the Designer Settings tab with the name "Period Range"
    var startDateString = dataSource.getSetting("Period Range").getValue().getFromPeriodStartDateTime().substring(0, 10);
    var endDateString = dataSource.getSetting("Period Range").getValue().getToPeriodEndDateTime().substring(0, 10);
    
    //get columns
    var columns = rowset.getColumns();

    for (var i = 0; i < dataSample.rows.length; i++) {
        var colName;
        var cells = [];
        for (var j = 0; j < columns.length; j++) {
            var colValue;
            var re = /\\\-/g;
            if ((new Date(dataSample.rows[i]["Effective Date"]) >= new Date(startDateString)) && (new Date(dataSample.rows[i]["Effective Date"]) < new Date(endDateString))) {
                colName = columns[j].getId();
                colValue = dataSample.rows[i][colName];
                cells.push(colValue.toString().replace(re, '.'));

            }
        }
        if (cells.length == columns.length) {
            //add rows
            rowset.addRow(cells);
        }
    }
}  

組合測試連線、匯入和預覽資料範例

//Consider a static JSON Data Sample set
dataSample = {
              rows: [
                        {"Value": 10, "Measure": "", "Test": "Palo Alto", "Effective Date": "2018-11-01"},
                        {"Value": 20, "Measure": " ", "Test": "Palo Alto", "Effective Date": "2018-11-01"},
                        {"Value": 30, "Measure": "  ", "Test": "Palo Alto", "Effective Date": "2018-11-01"},
                        {"Value": 40, "Measure": "   ", "Test": "Palo Alto", "Effective Date": "2018-11-01"},
                        {"Value": 50, "Measure": "1 ", "Test": "Pleasanton", "Effective Date": "2018-11-01"},
                        {"Value": 10, "Measure": "2  ", "Test": "Pleasanton", "Effective Date": "2018-12-01"},
                        {"Value": 20, "Measure": "3   ", "Test": "Pleasanton", "Effective Date": "2018-12-01"},
                        {"Value": 30, "Measure": "4    ", "Test": "Pleasanton", "Effective Date": "2018-12-01"},
                        {"Value": 40, "Measure": "5     ", "Test": "Pleasanton", "Effective Date": "2018-12-01"}
                    ]
               };
               
//Table Definition
ExternalMetadataDefinition = {
    Tables: [{
        name: "dataSample",
        displayName: "Sample",
        columns: [{
            name: "Value",
            displayName: "Value",
            type: "float",
            includeByDefault: true
        }, {
            name: "Measure",
            displayName: "Measure",
            includeByDefault: true
        }, {
            name: "Test",
            displayName: "Test",
            includeByDefault: true
        }, {
            name: "Effective Date",
            displayName: "Date",
            type: "datetime",
            includeByDefault: true
        }]
    }]
};                              
//Since this example uses a static data source,testConnection() function can return true
function testConnection(context) {
    return true;
}

//Import Structure
function importStructure(context) {    
        var addColumn = function(table, column, order) 
        {
            var recordColumn = table.addColumn(column.name);
            recordColumn.setDisplayName(column.displayName);
            switch (column.type) 
            {
                case "text":
                    recordColumn.setTextColumnType(column.length);
                break;
                case "int":
                    recordColumn.setIntegerColumnType();
                break;
                case "float":
                    recordColumn.setFloatColumnType();
                break;
                case "boolean":
                    recordColumn.setBooleanColumnType();
                break;
                case "datetime":
                    recordColumn.setDateTimeColumnType();
                break;
                default:
                    recordColumn.setTextColumnType(200);
                break;
          }
            recordColumn.setDisplayOrder(order);
            recordColumn.setIncludeByDefault(column.includeByDefault || false);
            recordColumn.setIncludeInKey(column.includeInKey || false);
            recordColumn.setMandatoryForImports(column.mandatoryForImport || false);
            recordColumn.setRemoteColumnType(column.remoteColumnType || "String");
        };    
     var builder = context.getStructureBuilder();    
     for (var i = 0; i < ExternalMetadataDefinition.Tables.length; i++)
     {
        var externalTable = ExternalMetadataDefinition.Tables[i];
        var table = builder.addTable(externalTable.name);
        table.setDisplayName(externalTable.displayName);        
        for (var j = 0; j < externalTable.columns.length; j++) 
        {
            addColumn(table, externalTable.columns[j], j + 1);
        }
    }
}
function previewData(context) {
    //Since the data is static, previewData() function can invoke importData()
    importData(context);
}
function importData(context) {
    var dataSource = context.getDataSource();
    var settings = dataSource.getSettings();
    var rowset = context.getRowset();
    
    //Set and Get SmartParsingEnabled() value
    rowset.setSmartParsingEnabled(true);
    ai.log.logInfo(getSmartParsingEnabled()); //true
    
    //Set a Start date and End date in the Designer Settings tab with the name "Period Range"
    var startDateString = dataSource.getSetting("Period Range").getValue().getFromPeriodStartDateTime().substring(0, 10);
    var endDateString = dataSource.getSetting("Period Range").getValue().getToPeriodEndDateTime().substring(0, 10);
    
    //get columns
    var columns = rowset.getColumns();

    for (var i = 0; i < dataSample.rows.length; i++) {
        var colName;
        var cells = [];
        for (var j = 0; j < columns.length; j++) {
            var colValue;
            var re = /\\\-/g;
            if ((new Date(dataSample.rows[i]["Effective Date"]) >= new Date(startDateString)) && (new Date(dataSample.rows[i]["Effective Date"]) < new Date(endDateString))) {
                colName = columns[j].getId();
                colValue = dataSample.rows[i][colName];
                cells.push(colValue.toString().replace(re, '.'));

            }
        }
        if (cells.length == columns.length) {
            //add rows
            rowset.addRow(cells);
        }
    }
}  

匯出資料函數 (僅限自訂雲端載入器)

環境定義參數

匯出資料函數附有 1 個參數「context」。

方法	參數	傳回類型	說明
createTableReader()	選用來源表格欄名稱陣列	TableReader	傳回作用中的資料來源。欄順序與參數中提供的順序相同。

TableReader 物件

方法	參數	傳回類型	說明
readRow()		值陣列	資料來源中的值陣列。

範例

// Manually invoke this method via 'Run manually'
function exportData(context) {
  // Step 1: Get the data
  var reader = context.createTableReader();

  // Step 2: Process and export the data
  var row = null;
  // If reader.readRow() returns null, then there are no more records.
  while ((row = reader.readRow()) !== null) {
    // Send the row to the external system or process it for a subsequent bulk update.
    ai.log.logInfo(JSON.stringify(row));
  }
}