# Project
@microsoft/powerappsauthoringsdk

## Note
- This is a preview feature.
- Preview features aren’t meant for production use and may have restricted functionality.
- These features are available before an official release so that customers can get early access and provide feedback.
- Microsoft doesn't provide support for this preview feature. Microsoft Technical Support won’t be able to help you with issues or questions.

### Description
- Launch PowerApps Studio to allow the user to create or edit canvas apps.
- Specify the form-factor (tablet or mobile) for a new application along with predefined templates.
- Subscribe to events from the Studio or Maker (like Studio Launched, App Saved, App Published) that describe the user’s interaction with the app and provides information (i.e., the application id) about the created app.
- Set schema for the data which can be passed to the application during authoring/runtime.
- Set data on the application during authoring time, this data shows up during authoring time but is not saved with application.
- Set host method definition which allows the application to callback into the host.

### Installation
```
npm install @microsoft/powerappsauthoringsdk
```

### Usage
For samples please visit: [Samples](http://aka.ms/powerappsembeddingsamples)

#### Import module into your project
```
import * as PowerAppAuthoringSdk from "@microsoft/powerappsauthoringsdk";
```

#### Initialize the SDK
```
const sdkInitializer: PowerAppsAuthoringSdk.SdkInitializer = { 
    hostName: “DemoApp”,
}
await PowerAppsAuthoringSdk.initAsync(sdkInitializer);
```

#### Edit app
```
const options: PowerAppsAuthoringSdk.EditAppOptions = {
    appId: <application id (GUID) which should be opened in edit mode>,
}
const session: PowerAppsAuthoringSdk.MakerSession = await PowerAppsAuthoringSdk.MakerSession.editAppAsync(options);
```

#### Create a new canvas app
```
const options: PowerAppsAuthoringSdk.CreateAppOptions = {
    appTemplate: <(optional) Template type>,
    displayName: <(optional) string display name>,
    environmentId: <(optional) environment Id (GUID) in which the app should be created>,
    externalCorrelationId: PowerAppsAuthoringSdk.initializeCv(),
    formFactor: <(optional) FormFactor phone or table, defaults to phone>,
    solutionId: <(optional) Solution Id (GUID) in which the app should be created, if specified then environment Id will be ignored>,
};
const session: PowerAppsAuthoringSdk.MakerSession = await PowerAppsAuthoringSdk.MakerSession.createAppAsync(options);
```

#### Create a new canvas app using a SQL Data Connection
How to get the connectionName/GUID
1. Visit www.web.powerapps.com.
2. In the left pane select Data->Connections.
3. Find your connection and click on it.
4. From the URL copy the GUID after 'connections/shared_sql/'
```
const options: PowerAppsAuthoringSdk.CreateAppOptions = {
    appTemplate: <(optional) Template type>,
    connectionName: <(required) The GUID identifying the connection>,
    databaseName: <(required) The name of your SQL database>,
    displayName: <(required) string display name>,
    environmentId: <(required) environment Id (GUID) in which the connection exists>,
    externalCorrelationId: PowerAppsAuthoringSdk.initializeCv(),
    formFactor: <(optional) FormFactor phone or table, defaults to phone>,
    serverName: <(required) The fully qualified SQL server name e.g. abc.windows.database.net>
    solutionId: <(optional) Solution Id (GUID) in which the app should be created, ensure that the solution exists in the same environment as that specified in environment Id>,
    tableId: <(required) The table identifier for the SQL DB table of the form [schema].[tablename]>
};
const session: PowerAppsAuthoringSdk.MakerSession = await PowerAppsAuthoringSdk.MakerSession.CreateAppWithSQLConnectionAsync(options);
```

#### Set the data schema
```
public async setSchemaAsync(schema: PowerAppsSchema): Promise<void>
```

#### Set the authoring time data
This data will not be saved with the application, this only shows up during authoring time.
```
public async setDataAsync(data: PowerAppsData): Promise<void> 
```

#### Set Host Method definition
The method definition is described using WADL.
```
public async setHostMethodDefinitionAsync(hostMethodDef: string): Promise<void> 
```

#### appSaved event
```
// Subscribe to application saved event 
function appSavedCallback(appInfo: PowerAppsAuthoringSdk.MakerSessionAppInfo) { 
    Console.log(“User saved application with id: “ + appInfo.appId);

    // If application is saved within a solution only then the following is valid
    Console.log(“User saved application with Logical Name: “ + appInfo.logicalName);
    Console.log(“User saved application in Environment: “ + appInfo.environmentId);
    Console.log(“User saved application in Tenant: “ + appInfo.tenantId);
} 
session.appSaved.subscribe(appSavedCallback);
```

#### appPublished event
```
// Subscribe to application published event 
function appPublishedCallback(appInfo: PowerAppsAuthoringSdk.MakerSessionAppInfo) { 
    Console.log(“User published application with id: “ + appInfo.appId);

    // If application is published within a solution only then the following is valid
    Console.log(“User published application with Logical Name: “ + appInfo.logicalName);
    Console.log(“User published application in Environment: “ + appInfo.environmentId);
    Console.log(“User published application in Tenant: “ + appInfo.tenantId);
} 
session.appSaved.subscribe(appSavedCallback);
```

#### Dispose an authoring session
Terminates or disposes of an ongoing maker session. Since at a time only a single maker session is supported, to create a second maker session the first session must be disposed of using this method. On successful completion of this method, all event listeners get automatically unsubscribed. Use this method with caution as the user may lose unsaved changes in the authoring session. This method takes no argument. 
```
await session.disposeAsync();
```

## License
See the [LICENSE](LICENSE) file for details