Please refer to the source code of this page for boilerplates (F12 for console).

1. Wiring up



Notes:
jQuery is required and should be included before the tEcs library (for ajax requests).
It is recommended to add local fallback version of the library if you use it in production (click "download" on the right).
We bear no responsibility for possible reachability interruption of directly linked components, they are useful to cold start your project and set up testing.

For extended APIs concerning SharePoint/WSD-SOAP go to tEcs+ (theobald.ecs)

2. Core APIs

tEcs.executeXql()

Example:
{
    data: "SELECT TOP 10 MATNR, MAKTX FROM MAKT"
}



tEcs.executeFunction()

Example:
{
    name: 'Z_ECS_GET_STOCK_INFO',
    data: {
        exports: {
            MATNR: '100-100'
        }
    }
}



tEcs.executeInScope()

Example (same for two functions):
{
    functions: [
        {
            name: "Z_PREPARE_REQ",
            data: {
                PARAMONE: "SOMEVALUE"
            }
        },
        {
            name: "Z_EXEC_REQ",
            data: function(){
                return parametersSapCheck;
            }
        }
    ]
}

3. Config

"connection" parameter should be passed to each of the above functions!
For ECS on premise this parameter is optional and tEcs will be working with defaults out of the box.
var connection = {
    ecs: {
        core: true,
        coreApiKey: "E370FB721AFA4EB2A86CC624E4B6890C",
        //serviceApplication: "ec2",
        url: "https://[namespace].servicebus.windows.net/ecs/ws"
    }
};
Optionally "done" and "fail" handlers could be passed to execute custom actions with result or error.
{
    connection: connection,
    done: function(data) {
        alert('Everything as planned!');
    },
    fail: function(data) {
        alert('Something broke :(');
    }
};
Full example of call executeFunction():
tEcs.executeFunction({
    connection: {
        ecs: {
            core: true,
            coreApiKey: "E370FB721AFA4EB2A86CC624E4B6890C",
            serviceApplication: "ec4",
            url: "https://ecscore.mydomain.com"
        }
    },
    data: {
        exports: {
            MATNR: '100-100'
        }
    },
    done: function(data) {
        alert('Everything as planned!');
    },
    fail: function(data) {
        alert('Something broke :(');
    },
    name: 'Z_ECS_GET_STOCKS'
});
Full example of call executeInScope():
var FUNCTION_TWO_PARAMETERS = {
    exports: {
        PARAMX: 'VALX'
    }
};

tEcs.executeInScope({
    // out of the box commit will be added after given functions
    // commit: true,
    connection: {
        ecs: {
            core: true,
            coreApiKey: "E370FB721AFA4EB2A86CC624E4B6890C",
            serviceApplication: "ec4",
            url: "https://ecscore.mydomain.com"
        }
    },
    // these "done" and "fail" will be executed when all functions are executed
    done: function(data) {
        alert('All funcitons executed!');
    },
    fail: function(data) {
        alert('Something broke :(');
    },
    functions: [
        {
            name: "FUNCTION_ONE",
            data: {
                PARAMONE: "SOMEVALUE"
            },
            // SET VALUES FOR THE NEXT FUNCTION
            done: function(data){
                // updating parameters of next function!
                FUNCTION_TWO_PARAMETERS.exports.PARAMTWO = data.imports.PARAMY;
            }
        },
        {
            name: "FUNCTION_TWO",
            // note, data is a function!
            data: function(){
                return FUNCTION_TWO_PARAMETERS;
            }
        }
    ],
});

4. Helper APIs

tEcs.getLastError()

Example:
$.ajax({
    url: 'http://somenonexistenturl.com'
}).fail(function() {
    console.log(tEcs.getLastError());
});
or
tEcs.executeFunction({
    name: "Z_ECS_GET_STOCK_INFO"
});


tEcs.testSapConnection()

Example:
tEcs.testSapConnection({
    connection: {
        ecs: {
            core: true,
            coreApiKey: "E370FB721AFA4EB2A86CC624E4B6890C",
            serviceApplication: "ec4",
            url: "https://ecscore.mydomain.com"
        }
    }
});

Live Test of your ECSCore


To test your own ECSCore Installation and it's SAP Service Applicaiton on the fly, use the fields below:





5. ECS Core Management APIs

tEcs.AddCredentialToSecureStore()

Example:
tEcs.AddCredentialToSecureStore({
    connection: {
        ecs: {
            coreApiKey: 'A1E2B883AC3141E29917F41CC92AE82B',
            url: 'https://myservicebus.servicebus.windows.net/ecs/ws'
        }
    },
        SecureStoreName: 'MySecureStore',
        UserOrGroup: 'MYDOMAIN\\MYUSER',
        // sap user
        Username: 'MYSAPUSER',
        // sap password
        Password: 'MYSAPPASSWORD'
});

tEcs.DeleteCredentialFromSecureStore()

Example:
tEcs.DeleteCredentialFromSecureStore({
    connection: {
        ecs: {
            coreApiKey: 'A1E2B883AC3141E29917F41CC92AE82B',
            url: 'https://myservicebus.servicebus.windows.net/ecs/ws'
        }
    },
        SecureStoreName: 'MySecureStore',
        // Secure Store user
        UserOrGroup: 'MYDOMAIN\\MYUSER'
});

tEcs.CheckCredentialInSecureStore()

Example:
tEcs.CheckCredentialInSecureStore({
    connection: {
        ecs: {
            coreApiKey: 'A1E2B883AC3141E29917F41CC92AE82B',
            url: 'https://myservicebus.servicebus.windows.net/ecs/ws'
        }
    },
        SecureStoreName: 'MySecureStore',
        // Secure Store user
        UserOrGroup: 'MYDOMAIN\\MYUSER',
        done: function(checkedOk){
            if(checkedOk){
                alert('Legit user!');
            }
        }
});

All functions return deferred. Done/Fail as parameters supported:
done: function(response){
    if (response === "OK") {
        alert('ALL GOOD!');
    }else{
        console.log(response);
    }
},
fail: function(response){
    console.log(response);
    alert(response.error.message);
}
                    

Live Manage of YOUR ECSCore SecureStore


Try to manage your own ECSCore Installation on the fly, use the fields below:

Connection:



Secure Store parameters:



Required for Add:



6. Typical usage patterns

6.1. Scalar Parameter

to SAP (exports): DELIV_DATE
from SAP (imports): ORDER_NUM
tEcs.executeFunction({
    //connection: {}
    name: 'BAPI_PO_CREATE',
    data: {
        exports: {
            // to SAP
            DELIV_DATE: "20141022"
        },
        done: function(data){
            // from SAP
            alert(data.imports.ORDER_NUM);
        }
    }
});
//
// use an empty object to prepare parameters
var exports = {},
    sapDeliveryDateParameter = "20141022";
//
// set parameters values
exports.DELIV_DATE = sapDeliveryDateParameter;
//
// execute function with parameters
tEcs.executeFunction({
    //connection: {}
    name: 'BAPI_PO_CREATE',
    data: {
        exports: exports
    },
    done: function(data){
        // input scalar parameter
        alert(data.imports.ORDER_NUM);
    }
});

6.2 Vector Parameter

to SAP (exports): PO_HEADER
from SAP (imports): PO_CHECKED
tEcs.executeFunction({
    //connection: {}
    name: 'BAPI_PO_CREATE',
    data: {
        exports: {
            PO_HEADER: {
                    PO_ITEM: "1",
                    DELIV_DATE: "20141022",
                    QUANTITY: 10
            }
        }
    }
});
//
// use an object to prepare a vector parameter
var po_header;
po_header.DOC_TYPE = "NB";
po_header.PURCH_ORG = "1000";
po_header.PUR_GROUP = "010";
po_header.VENDOR = "0000001070";

tEcs.executeFunction({
    //connection: {}
    name: 'BAPI_PO_CREATE',
    data: {
        exports: {
            PO_HEADER: po_header
        }
    },
    done: function(data){
        // read when function is executed
        var po_checked = data.imports.PO_CHECKED;
        // field of the vector parameter
        alert(po_checked.QUANTITY);
    }
});

6.3 Table Parameter

to SAP (exports): PO_ITEM_SCHEDULES
from SAP (imports): PO_ITEM_CHECKED
tEcs.executeFunction({
    //connection: {}
    name: 'BAPI_PO_CREATE',
    data: {
        exports: {
            PO_ITEM_SCHEDULES: [{
                    PO_ITEM: "1",
                    DELIV_DATE: "20141022",
                    QUANTITY: 10
                }
            ]
        }
    }
});
//
// use an array to fill a table
var po_item_schedules = [];
po_item_schedules.push({
    PO_ITEM: "1",
    DELIV_DATE: "20141022",
    QUANTITY: 10
});

tEcs.executeFunction({
    //connection: {}
    name: 'BAPI_PO_CREATE',
    data: {
        tables: {
            PO_ITEM_SCHEDULES: po_item_schedules
        }
    },
    done: function(data){
        // shortcut to array
        var po_item_checked = data.imports.PO_ITEM_CHECKED;
        // first element
        alert(po_item_checked[0]);
    }
});

6.4 Parameters between functions in scope

output first function: VENDORS
input second function (exports): PROVIDERS
// local variable to store required parameters
var parameters_Z_EXEC_REQ = {
    exports: {
        SOME_CONSTANT_PARAMETER: 3
    }
};
tEcs.executeInScope({
    functions: [
        {
            name: "Z_PREPARE_REQ",
            data: {
                PARAMONE: "SOMEVALUE"
            },
            done: function(data){
                // set required for the next function parameter
                parameters_Z_EXEC_REQ.exports.PROVIDERS = data.exports.VENDORS;
            }
        },
        {
            name: "Z_EXEC_REQ",
            // function returns "dynamic" value of parameters, when they were set/updated after first function
            data: function(){
                return parameters_Z_EXEC_REQ;
            }
        }
    ]
})

6.5 Parameters between functions in scope (embedded syncObject)

output first function: VENDORS
input second function (exports): PROVIDERS
//variable to automatically handle in/out parameters
var syncObject = {};
//
tEcs.executeInScope({
    syncObject: syncObject,
    functions: [
        {
            name: "Z_PREPARE_REQ",
            data: {
                PARAMONE: "SOMEVALUE"
            },
            // no "done", nothing special should be made
        },
        {
            name: "Z_EXEC_REQ",
            // function returns "dynamic" value of parameters, when they were set/updated after first function
            data: function(data){
                // when first function is executed,
                // system variable syncObject is set with RESULT from this executed function,
                // so we have access to it through "syncObject" plus executed function name, e.g. "Z_PREPARE_REQ":
                var second_function_parameters = {
                    exports: {
                        PROVIDERS: syncObject.Z_PREPARE_REQ.exports.VENDORS
                    }
                };

                return second_function_parameters;
            }
        }
    ]
})

6.6 Scope commit

tEcs.executeInScope({
    // executes BAPI_TRANSACTION_COMMIT when all functions are executed
    commit: true,
    done: function(data){
        alert('Function chain completed (with Commit)');
    },
    fail: function(data){
        alert(JSON.stringify(data));
    },
    functions: [
        {
            name: "Z_PREPARE_REQ",
            data: {
                PARAMONE: "SOMEVALUE"
            },
            done: function(data){
                alert('Custom action after first function!');
            }
        }
    ]
})

6.7 Composing functions

//executes asynchroneously SAP-function and XQL-Query
// when both are executed, print results
$.when(
    tEcs.executeFunction({ name: "Z_GET_MY_USERNAME" },
    tEcs.executeXql({query: "SELECT TOP 10 MAKTX FROM MAKT"}))
.then(function(results){
    // prints my username
    console.log(results[0].exports.USR_NAME);
    // prints materials
    console.log(results[1])
})

7. Summing up

Extended logging and error handling: parsing/unwrapping of XHR, ECSCore responses.
Out of the box functionality with minimum parameters.
No configuration needed.

8. Changelog.

4.12 deferreds upgrades, added paragraph 6.7 with combining function requests
4.11 improved support for deferreds in executeFunction, executeInScope and executeChain
4.10 fixed wrong extend function causing ajax parameters set to incorrect values when custom jQuery is on the page
4.9 serviceApplication parameter for consistency (synonym for "instance")
4.8 Support for SecureStore Management APIs
4.7 Support for Scope and Instances (Service Applications) in ExecuteXQL queries
4.6 Proper Xhr aborting on user abort
4.5 Added functions to test connection
– Implemented recognition mechanism for SharePoint Online
– Implemented beta support without jQuery
– Added Support for XQL-Queries inside the scope
– Modified Authorization behavior, support for ECSCore 1.1.158+
4.1 Added "coreApiKey" field to use with new Api-Mechanism (ECSCore-APIKEY header)