docs: update graphql docs on forms & structured properties (#11100)

docs/api/tutorials/forms.md

@@ -9,16 +9,16 @@ Documentation Forms are a way for end-users to fill out all mandatory attributes
 
 Learn more about forms in the [Documentation Forms Feature Guide](../../../docs/features/feature-guides/documentation-forms.md).
 
-
 ### Goal Of This Guide
-This guide will show you how to create and read forms.
+This guide will show you how to 
+- Create, Update, Read, and Delete a form
+- Assign and Remove a form from entities
 
 ## Prerequisites
 
 For this tutorial, you need to deploy DataHub Quickstart and ingest sample data.
 For detailed information, please refer to [Datahub Quickstart Guide](/docs/quickstart.md).
 
-
 <Tabs>
 <TabItem value="CLI" label="CLI">
 
@@ -29,14 +29,45 @@ Connect to your instance via [init](https://datahubproject.io/docs/cli/#init):
 2. Set the server to your sandbox instance, `https://{your-instance-address}/gms`
 3. Set the token to your access token
 
-
 </TabItem>
 </Tabs>
 
-
 ## Create a Form
 
 <Tabs>
+<TabItem value="graphQL" label="GraphQL">
+
+```graphql
+mutation createForm {
+ createForm(
+ input: {
+ id: "metadataInitiative2024",
+ name: "Metadata Initiative 2024",
+ description: "How we want to ensure the most important data assets in our organization have all of the most important and expected pieces of metadata filled out",
+ type: VERIFICATION,
+ prompts: [
+ {
+ id: "123",
+ title: "retentionTime",
+ description: "Apply Retention Time structured property to form",
+ type: STRUCTURED_PROPERTY,
+ structuredPropertyParams: {
+ urn: "urn:li:structuredProperty:retentionTime"
+ }
+ }
+ ],
+ actors: {
+ users: ["urn:li:corpuser:jane@email.com", "urn:li:corpuser:john@email.com"],
+ groups: ["urn:li:corpGroup:team@email.com"]
+ }
+ }
+ ) {
+ urn
+ }
+}
+```
+
+</TabItem>
 <TabItem value="CLI" label="CLI">
 
 Create a yaml file representing the forms you’d like to load. 
@@ -111,8 +142,42 @@ If successful, you should see `Created form urn:li:form:...`
 </TabItem>
 </Tabs>
 
-## Read Property Definition
+## Update Form
 
+<Tabs>
+<TabItem value="graphQL" label="GraphQL">
+
+```graphql
+mutation updateForm {
+ updateForm(
+ input: {
+ urn: "urn:li:form:metadataInitiative2024",
+ name: "Metadata Initiative 2024",
+ description: "How we want to ensure the most important data assets in our organization have all of the most important and expected pieces of metadata filled out",
+ type: VERIFICATION,
+ promptsToAdd: [
+ {
+ id: "456",
+ title: "deprecationDate",
+ description: "Deprecation date for dataset",
+ type: STRUCTURED_PROPERTY,
+ structuredPropertyParams: {
+ urn: "urn:li:structuredProperty:deprecationDate"
+ }
+ }
+ ]
+ promptsToRemove: ["123"]
+ }
+ ) {
+ urn
+ }
+}
+```
+
+</TabItem>
+</Tabs>
+
+## Read Property Definition
 
 <Tabs>
 <TabItem value="CLI" label="CLI">
@@ -146,3 +211,60 @@ If successful, you should see metadata about your form returned like below.
 
 </TabItem>
 </Tabs>
+
+## Delete Form
+
+<Tabs>
+<TabItem value="graphQL" label="GraphQL">
+
+```graphql
+mutation deleteForm {
+ deleteForm(
+ input: {
+ urn: "urn:li:form:metadataInitiative2024"
+ }
+ )
+}
+```
+</TabItem>
+</Tabs>
+
+## Assign Form to Entities
+
+For assigning a form to a given list of entities: 
+
+<Tabs>
+<TabItem value="graphQL" label="GraphQL">
+
+```graphql
+mutation batchAssignForm {
+ batchAssignForm(
+ input: {
+ formUrn: "urn:li:form:myform",
+ entityUrns: ["urn:li:dataset:mydataset1", "urn:li:dataset:mydataset2"]
+ }
+ )
+}
+```
+</TabItem>
+</Tabs>
+
+## Remove Form from Entities
+
+For removing a form from a given list of entities:
+
+<Tabs>
+<TabItem value="graphQL" label="GraphQL">
+
+```graphql
+mutation batchRemoveForm {
+ batchRemoveForm(
+ input: {
+ formUrn: "urn:li:form:myform",
+ entityUrns: ["urn:li:dataset:mydataset1", "urn:li:dataset:mydataset2"]
+ }
+ )
+}
+```
+</TabItem>
+</Tabs>

docs/api/tutorials/structured-properties.md

@@ -56,7 +56,33 @@ Requirements for OpenAPI are:
 The following code will create a structured property `io.acryl.privacy.retentionTime`. 
 
 <Tabs>
-<TabItem value="CLI" label="CLI" default>
+<TabItem value="graphql" label="graphQL" default>
+
+```graphql
+mutation createStructuredProperty {
+ createStructuredProperty(
+ input: {
+ id: "retentionTime",
+ qualifiedName:"retentionTime",
+ displayName: "Retention Time",
+ description: "Retention Time is used to figure out how long to retain records in a dataset",
+ valueType: "urn:li:dataType:number",
+ allowedValues: [
+ {numberValue: 30, description: "30 days, usually reserved for datasets that are ephemeral and contain pii"},
+ {numberValue: 90, description:"description: Use this for datasets that drive monthly reporting but contain pii"},
+ {numberValue: 365, description:"Use this for non-sensitive data that can be retained for longer"}
+ ],
+ cardinality: SINGLE,
+ entityTypes: ["urn:li:entityType:dataset", "urn:li:entityType:dataFlow"],
+ }
+ ) {
+ urn
+ }
+}
+```
+
+</TabItem>
+<TabItem value="CLI" label="CLI">
 
 Create a yaml file representing the properties you’d like to load. 
 For example, below file represents a property `io.acryl.privacy.retentionTime`. You can see the full example [here](https://github.com/datahub-project/datahub/blob/example-yaml-sp/metadata-ingestion/examples/structured_properties/struct_props.yaml).
@@ -355,7 +381,37 @@ Example Response:
 This action will set/replace all structured properties on the entity. See PATCH operations to add/remove a single property.
 
 <Tabs>
-<TabItem value="CLI" label="CLI" default>
+<TabItem value="graphQL" label="GraphQL" default>
+
+```graphql
+mutation upsertStructuredProperties {
+ upsertStructuredProperties(
+ input: {
+ assetUrn: "urn:li:mydataset1",
+ structuredPropertyInputParams: [
+ {
+ structuredPropertyUrn: "urn:li:structuredProperty:mystructuredproperty",
+ values: [
+ {
+ stringValue: "123"
+ }
+ ]
+ }
+ ]
+ }
+ ) {
+ properties {
+ structuredProperty {
+ urn
+ }
+ }
+ }
+}
+
+```
+
+</TabItem>
+<TabItem value="CLI" label="CLI">
 
 You can set structured properties to a dataset by creating a dataset yaml file with structured properties. For example, below is a dataset yaml file with structured properties in both the field and dataset level. 
 
@@ -466,6 +522,31 @@ Or you can run the following command to view the properties associated with the
 datahub dataset get --urn {urn}
 ```
 
+## Remove Structured Properties From a Dataset
+
+For removing a structured property or list of structured properties from a dataset:
+
+<Tabs>
+<TabItem value="graphql" label="GraphQL" default>
+
+```graphql
+mutation removeStructuredProperties {
+ removeStructuredProperties(
+ input: {
+ assetUrn: "urn:li:mydataset1",
+ structuredPropertyUrns: ["urn:li:structuredProperty:mystructuredproperty"]
+ }
+ ) {
+ properties {
+ structuredProperty {urn}
+ }
+ }
+}
+```
+
+</TabItem> 
+</Tabs>
+
 ## Patch Structured Property Value
 
 This section will show you how to patch a structured property value - either by removing, adding, or upserting a single property.
@@ -780,6 +861,38 @@ You can see that the first property has been removed and the second property is
 In this example, we'll add the property back with a different value, preserving the existing property.
 
 <Tabs>
+<TabItem value="graphql" label="GraphQL">
+
+```graphql
+mutation updateStructuredProperty {
+ updateStructuredProperty(
+ input: {
+ urn: "urn:li:structuredProperty:retentionTime",
+ displayName: "Retention Time",
+ description: "Retention Time is used to figure out how long to retain records in a dataset",
+ newAllowedValues: [
+ {
+ numberValue: 30,
+ description: "30 days, usually reserved for datasets that are ephemeral and contain pii"
+ },
+ {
+ numberValue: 90,
+ description: "Use this for datasets that drive monthly reporting but contain pii"
+ },
+ {
+ numberValue: 365,
+ description: "Use this for non-sensitive data that can be retained for longer"
+ }
+ ]
+ }
+ ) {
+ urn
+ }
+}
+
+```
+
+</TabItem>
 <TabItem value="OpenAPI v2" label="OpenAPI v2">
 
 ```shell

docs/features/feature-guides/documentation-forms.md

@@ -101,7 +101,7 @@ You sure can! Please keep in mind that an Asset will only be considered Document
 
 ### API Tutorials
 
-- [Create a Documentation Form](../../../docs/api/tutorials/forms.md)
+- [API Guides on Documentation Form](../../../docs/api/tutorials/forms.md)
 
 :::note
 You must create a Structured Property before including it in a Documentation Form.