2 Setup In order to start using our AWESOME API one needs to set up a few things. We will summarize first the steps needed to achieve this and then detail them. Understanding the wording Coresystems Cloud Account – the account that you have to create in order to have a Coresystems identity. There are 3 types of accounts: With ERP: data will be synchronized with ERPs. Stand-alone: the data will be ONLY on the cloud, there is no synchronization with an ERP. Trial:a standalone account that is valid for 30 days from the time it is created; contains demo company with demo data and highest subscription and permission types along with 5 demo users. Coresystems Cloud Company – the virtual storage database that contains information relevant to your company Coresystems Cloud User – the user that you will give to your employees to access the cloud data. This cloud user will have a set of subscriptions and permissions. There are 3 types of Person but only ERPUSER can be assigned to the cloud user. The person types are: ERPUSER is used as one of the main constraints when it comes to data filtering and ownership, it will also be the “person” that creates objects in case of data coming to the cloud. SALESEMPLOYEE is used when it comes to sales objects and business partners. EMPLOYEE it is the person type that links other types together. Most of the ERPs have a person type like this that allows centralizing the information related to a person/user. Important to know: cloud users do not belong to a company, they belong to an Account. Coresystems subscription –the virtual templates that allow you transfer certain data to and from the cloud, see Coresystems Field Service Software for more information. Coresystems permissions –the virtual constraints that you, as a manager, would like to set up for a cloud user. They are dependent on the type of subscriptions you have already assigned. 2.1 Create a Coresystems Account. The Coresystems account is the first thing you need to create in order to use the Coresystems platform. But how does someone do it? Let’s see: Navigate to Coresystems store. Here we can see the main page of the Coresystems store. There are two possibilities from this point: A Trial account. Fully working account. We will create a fully working account, for this select Register on the main page. In the following screen, fill in the account name and the e-mail you would like to receive the account confirmation email. Shortly you will receive a email that contains the registration link. Click on it. You will be redirected to the Account registration page where you will have to specify the information related to your company. The most important information needed to be specified here are: Data location – depending on it, your database will be created on specific regions. This will affect mainly latency. Account Type – see Step 0, Coresystems Cloud Account. For demo purposes we will create a Stand-Alone company. Once you fill in all the information, click on “Create” and the Account will be created. Click “Continue” to reach the main page of the newly created Account. Superb! Now you have a Stand-Alone Coresystems Cloud Account. Let’s go to the next Step! 2.2 Buy Subscriptions The first thing you need to do after the Account is created is to buy some subscriptions. Let’s see how we can do this: In the main page of the newly created Account, click on the “Buy subscriptions” link. Depending on your needs select the most suitable subscription type for you by clicking on the shopping bag next to it. For demo purposes I will use FIELD SERVICE GLOBAL. This will take you to the next screen. In this screen you need to have at least 5 subscription types in total for you to place an order (the price is recalculated each time you modify the quantity). Once this is settled and Checkout is available, click on it. This will take you to the Checkout confirmation screen. Confirm the order by clicking on “Continue”. This will take to the sales order detail screen. Click on “Continue”. Once you receive the invoice and the payment is done, the subscriptions will be available for you to use. Note that they will not be usable until the payment is performed and the order is confirmed. After they are confirmed, you will see them in the “My subscriptions”. Cool! Now you have your subscriptions ready. Let’s go to the next step and create a company. 2.3 Create a Company Now we are ready to create a company that will store our data on the cloud. Let’s see how we can do that: First we need to navigate to the “Companies” screen. As we can see, there are no companies, let’s create one by clicking on the “Create” button. In this screen, fill in the name of the company and, if needed the description. Finish creating the company by clicking on the “Create” button. In the blink of an eye, the company is created. Now we are at the Companies screen again where we can see our newly created company. Name and description of the company. Synchronization status (this is usually used for companies that are created for accounts with ERP). We can see the company Database size (computed once a day - midnight). Attachments size. When it was the database size computed. We can delete the company (by pressing the “Delete” button). Refresh the company list (by pressing the Refresh button). Create a new company (by pressing the the “Create” button). It is important to know now on which cluster our company created. We can do this by doing a GET REST call with the following url (replace “DemoCloudAccount” with your account name):https://ds.coresuite.com/ds/api/directory/v1/accounts/DemoCloudAccount This will return a JSON that contains the following information: accountName – name of the account (DemoCloudAccount) accountId – the cloud Id of the account (178389) clusterName – the name of the cluster the account was created on. url – the url of the master cloud. This is very important because this is where we will do the calls. (https://eu.Coresystems.com) 2.4 Create a Cloud User What is a “Cloud User”? The cloud user is the entity responsible for transferring data between the cloud and the application. This will be the key used to send data to the cloud. In order to create a cloud user, we have to follow the next steps: Navigate to the Cloud Users page; we do this by selecting the “Cloud Users” link. No cloud users? Let’s fix that! Click on the “Create” button. In case you do not have a cloud user default password set (which in our case we do not) the cloud is kind enough to let you specify one. Enter a password and click on “Update”. A bit more about passwords“Cloud users are always asked to change the password the first time they log in using one of the clients. If you change the default cloud user password, it is applied only to users who haven't changed their initial password yet.”The default password is applied to users added using other means (via connectors or via API). Once we get this out of the way and we have set up a default password, we will reach the user creation screen. Fill in the mandatory information and click on “Create”(we need to set up the default password for this user as this is created by the administrator). You will be taken to the Cloud Users screen and you can see your newly created Cloud User. NOTE: at this moment you will not be able to use the APIs. You will have to log in and change the password for the user, as the current one is the default one. You can do this by logging in (my.coresuite.com) with your Cloud Account / Cloud User / Default Password (set in the store). It will take you to the change password screen where you can set up a permanent password. Good Job! 2.5 Create Permissions Group Let’s now create a permissions group that we can assign to our cloud user. Coresystems has already generated some standard permissions groups that fill some of the roles your FSM company may have, but you can customize them to fit your own needs as needed. Let’s find out how we can create Permissions group: Let’s click on the “Cloud Users” link so we can navigate to the “Permissions groups”. Once the “Cloud Users” page is loaded, let’s go ahead and click on the “Permissions groups” button. In the Permissions page we will see the default permissions created by coresystems. Now we can create a new one by clicking on “Create a permission group” button. Now we have reached the create permission group section. It’s important to note that each business object has its own permission section. Let’s take a moment and observe the screen: Name and Description – the name and description of the permission group you are about to create. Business Object – represents one of the business objects that the user will have access to. Create / Read / Update / Delete – possible actions on that specific business object. Advanced actions – these are special options that allow the user to customize the way that Coresystems applications behave. (ex: visible – will show or hide this specific module) Once you have set up all the permissions accordingly go ahead and click on “Create” button. This will create the subscription and take you back to the Permissions groups screen. Now we have the new permissions group ready to be used. 2.6 Assign Subscriptions to Cloud User This means that this user will be allowed to synchronize to and from the cloud a certain set of business objects. The subscriptions are a template of what the user may do. Let’s go ahead and assign subscriptions to our demo user. In the Coresystems store, click on “Assign subscriptions” link. Lets take a moment and take a look at this screen: Subscription type – dropdown that contains all subscriptions your account has. Company – to assign the license to. Available users – the list of users that you can assign you licenses to. Assigned users – the list of users that already have licenses assigned to. Add or remove subscriptions – adding or removing users from and to subscriptions. Save – button that saves the changes done. Make sure you have selected a) the correct subscription type and b) the correct company. Select the user you want to assign the subscription to from column c). Add button e) should be enable. Click on Add button. User should migrate to “Assigned users” column. Save button f) is enabled. Click the Save button f). Once the modifications are saved you will see “The subscriptions have been assigned.” on the black bar below the users list. At this point, your user has the permissions it needs! 2.7 Assign Permission Group to User The next thing we will need to do is assign the permission to the user in order for it to be able to do calls to the cloud. Let’s assign the demo permission we created in step 5. From the store main page click on the “Cloud users” link. Search for the cloud user you want to add the permission to. Click on the user. Click on the dropdown list corresponding to your company in the “Linked permission groups” section. Chose the permission group you want to assign (“Demo Permission Group” in our case). Click on “Update”. Once the changes are saved, the user will be taken to the “Cloud Users” page. We are almost done! Good job! 2.8 Try Out the API Note: Coresystems uses OAuth 2.0 for authorization. For more information on OAuth 2.0, including information, refer to the following topic. Now we have all the information and all the steps done in order to do the first calls to the cloud. We will do a GET REST call with the following url: https://eu.coresuite.com/api/data/v4/Person?accountName=DemoCloudAccount&userAccountName=DemoUser&userAccountPassword=password&companyName=DemoCompany&dtos=Person.19&clientIdentifier=COR_CON_NONE This will return all the Person business objects that are available for your company! With this we have finished our demo. Keep up the good work!