In our previous post, we described the example Corporate Directory app that we built using the SAP Cloud Platform for iOS SDK. Now let’s take a look at how we started the project in SAP’s Cloud Portal, and how we used the SAP Cloud Platform SDK for iOS Assistant to generate an Xcode project.
In the Cloud Platform web portal, we started a native application by selecting Mobile Applications | Native Hybrid from the menu, and then the New button above the list of mobile applications:
We selected the Native option from the Config Templates choices, which will allow the SAP Cloud Platform for iOS Assistant to generate an Xcode project. For the ID field, we entered the bundle ID that we would like to use for the app. This is typically a reverse-DNS style unique identifier for an app in the app store. The Name field is what SAP will use to display in the list of mobile applications. Description and Vendor can be used at your discretion.
After the application is created in the portal, an info screen will be displayed that shows what was entered. Note that the “Connectivity” item in the list of Assigned Features will show “Incomplete Configuration.” This is where we need to tell the portal what information we would like to access with the app.
Finding Your Entity and Setting up a Mobile Destination
We browsed through the Success Factors API data to find User Management, which looked like it would have the information necessary to complete our contact list. There are two important pieces of information available on this screen: the API Endpoint and a link to Get API Key.
Once we found this page, we returned to the info page for our newly created app and clicked on the Connectivity item in the Assigned Features List, and selected the Create button to create a new Destination for the app.
We selected Mobile Destination as the type, and provided a name for the destination. Note: the name cannot contain spaces.
In the next screen, we pasted in the URL from the User Management API screen, and left the rest of the fields with their default values. Next, we set up the APIKey for the destination (from the “Get API Key” button on the User Management API page shown previously):
Finally we made sure the endpoint has No Authentication set, and completed creation of the destination.
Starting the Xcode project
Once we set up the application and destination in the portal, we used the SAP Cloud Platform SDK for iOS Assistant to generate an Xcode project. This is a really powerful feature of the SDK – the Assistant is a macOS application which will create boilerplate code for the selected model entities, and will build a skeleton user interface to access the selected entities. While this created code will not be close to what we would want to ship to users, it saves a lot of time and simplifies the development process.
In the Assistant, we hit the plus button to start a new project. This kicks off a series of four screens to collect information about the app:
In Project Properties, we specified the Product Name, which becomes the Xcode project name. We specified the Author and Organization Name, which then get used by the Xcode project in generated source code headers. We specified the Organization Identifier, a reverse-DNS style identifier which is then used to build the Bundle Identifier. Note: this must match the Bundle Identifier specified previously when setting up the application in the Cloud Portal, and must be unique for an app in the app store. Finally, we specified where we would like to save the project.
In the Cloud Configuration setting, we selected our account for the app. This presumes that we set up the account in the Assistant prior to adding the project. There are three options then for creating a new app: Create, Use Existing, and Sample. In our case we selected Use Existing since we had already created the application and destination in the portal, and selected the application that we had created.
In the OData Services section, we confirmed that the destination we set up in the portal was displayed – this information is pulled from the portal by the Assistant.
Finally, we accepted the defaults for Optional Features, which include choices for creating the Master/Detail screens, logging, and push notifications. After a few moments, the Assistant had created an Xcode project for us.
After some trial and error, and discussion with SAP technical resources, we discovered that two minor adjustments were required to the generated code in order to access the destination correctly. The first adjustment was in the OnboardingManager.swift file, in the configuredWelcomeScreenStep() method. We added “$metadata” to the end of the discoveryConfigurationTransformer’s authenticationPath parameter as shown:
In the AppDelegate’s configureOData(…) method, we needed to remove the $metadata path element that we added in the previous step. We did that as follows:
Running the app with those changes looks like this:
The user can select an entity, and then see a list of instances.
Clearly this is not what we would like to present to users; but all the “plumbing” is in place so we only needed to update the user interface to our design before adding more advanced features like Search. We will explore the customizations we performed to the iOS project in our next post.