Connect a projection function to its implementation

I · Integration / 26R1 reference / Documentation-based walkthrough draft

Build a customer-owned API function that changes demo-ho-014 into DEMO-HO-014. Follow the service contract through implementation, deployment, permissions, and an authenticated HTTP call.

This example has not been compiled or run in IFS. The component DEMO and projection CDemoReferenceService are fictional aliases. Replace them with the names and component approved for your solution.

Before you start

You need a compatible Developer Studio build home and target version, a nonproduction development database, a customization project, and a build/deployment process. An administrator must be able to grant the new projection to a dedicated test identity. For an external caller, complete authentication and access setup first.

Check API discovery before building a new API; an existing supported operation may already satisfy a real requirement. This exercise demonstrates a new pure function. It does not create or update business records.

Download the target worksheet, reference test cases, standalone SQL checks, and acceptance checks. None is an importable IFS service package.

1. Create or open the customization project

Confirm the build home’s release and Developer Studio target version match your environment.
If the project does not exist, choose File → New Project → IFS → IFS Customization Project → Next.
Supply the project name/location and target version, select the required database technology, configure the authorized development database connection, and finish the wizard. Use the project’s established component and build-home configuration.
In the project’s model area, create a new projection using the projection model/template supported by your installed toolchain. Set its component to your actual development component and its layer to Cust.
Keep it customer-owned. Customize This is the workflow for extending an existing parent projection; this exercise defines a new one.

2. Define the operation contract

Enter the following in the new .projection, substituting your component. Use your project’s generated filename/location, typically CDemoReferenceService-Cust.projection.

projection CDemoReferenceService;
component DEMO;
layer Cust;
category Integration;

function NormalizeReference Text {
   parameter Reference Text;
}

The caller supplies Reference. The implementation removes leading/trailing ordinary spaces and uppercases the remaining text. It preserves spaces inside the value. A value consisting entirely of ordinary spaces produces Oracle null.

The parameter declaration does not explicitly make the parameter optional. Omitting a required HTTP parameter is different from supplying spaces. Inspect the generated contract and test those cases separately. The Oracle null case in the SQL download tests the implementation; it does not promise that an HTTP caller may omit a required argument.

This example does not enforce a 50-character business limit. The 50/51-character cases demonstrate preservation within the service’s supported size. If your real field has a 50-character limit, define and test an explicit validation rule instead of silently truncating longer values.

3. Generate and fill the service stub

Save and generate the projection with the configured toolchain.
Open the generated/associated Cust .plsvc implementation source. Use its method signature, parameter names, and types as authoritative.
Implement the generated operation with the expression below, preserving other methods and the file header.
Generate again and inspect compilation/generation messages. Resolve errors before proceeding to API tests.

The expected simple implementation pattern is:

layer Cust;

FUNCTION Normalize_Reference___ (
   reference_ IN VARCHAR2) RETURN VARCHAR2
IS
BEGIN
   RETURN UPPER(TRIM(reference_));
END Normalize_Reference___;

Do not wrap this model service source in CREATE PACKAGE, and do not paste it into the generated deployed database package. If your generator produces a different signature, adapt the body to that signature.

Artifact	Responsibility
`.projection`	Operation name, input, return type, service category
`.plsvc`	Implementation of the generated method
Generated service metadata	Actual consumer contract
Permission set	Caller access
`.plsvt`, where supported by the project	Service regression checks using that project’s test conventions

A function must remain free of business-state changes. If you need to create or update records, design an appropriate action with validation and transaction behavior.

4. Check the expression separately

Open normalize-reference-check.sql in an approved Oracle development SQL client.
Enable its DBMS_OUTPUT display and execute the file as a script. The file defines a local function inside an anonymous block; it creates no schema object and changes no business rows.
Expect seven PASS messages followed by a final count. A mismatch raises an exception.
Retain the result with the Oracle environment information. These checks have not been run by this website in Oracle.

The cases cover ordinary-space trimming, unchanged normalized input, internal spaces, blank/null handling, and 50/51-character preservation. TRIM here is not a universal Unicode-whitespace normalizer. For tabs, non-breaking spaces, or locale-sensitive case rules, agree the required behavior and add explicit tests.

Checkpoint: the expression’s behavior is understood independently of HTTP routing and permissions.

5. Deploy and discover the actual API

Build/generate and deploy the service through your nonproduction development process. Inspect logs and confirm that no invalid generated objects remain.
In IFS Cloud, open API Explorer and find the actual projection name. Confirm its layer and environment.
Choose OpenAPI v3 or OData Service Document to inspect the generated contract. Documentation → API Doc opens the interactive documentation view.
Locate NormalizeReference. Record its HTTP method, complete operation URL, parameter spelling, encoding, and response schema in the worksheet.
Export/import the generated OpenAPI specification into your API client if that is your team’s normal workflow. Use the generated request; do not derive a production URL from the fictional projection name here.

Checkpoint: the deployed operation appears in the specification with the expected input and return type. A local method that compiles but is absent from this contract is not ready for a consumer.

6. Grant the test caller access

Open the dedicated test Permission Set and its projection grants.
Use Add to grant only the actual new projection. Do not use Add All to make the exercise work.
Inspect Manage Projection Grants and choose the least access that supports this read-only function. The UI also exposes action grants; those should not be confused with this function’s contract.
Assign the permission set to the intended test identity through your environment’s user/identity setup.
Obtain an access token for that identity using the configured OAuth flow. Keep tokens in your API client’s local secret storage, not a shared worksheet or exported collection.
Keep a second authenticated test identity without the grant for the negative check.

Being able to read documentation or metadata does not prove that the identity may execute the operation. Test invocation itself.

7. Call the function and inspect the response

Open the generated operation request in your API client and select the test environment.
Supply a fresh bearer token and the required Reference parameter with the value demo-ho-014.
Let the client’s generated request encode the value according to the specification. OData literal quoting and URL encoding are separate concerns; typing an unescaped URL by hand can corrupt spaces or apostrophes.
Send the request using the documented method. Inspect the status, response body, and the exact return property described by the schema.
Expect the returned value DEMO-HO-014. Record the actual response shape rather than assuming it is always a bare string or always a value property.
Repeat with DEMO-HO-014, demo ho 014, and ordinary spaces only. The expected values are unchanged text, DEMO HO 014, and null respectively, if that blank argument is admitted by the generated HTTP contract.
Omit the required parameter and confirm the documented validation response. This is a contract error, not the same test as sending spaces.
Repeat the valid request as the authenticated identity without the projection grant. Expect access to be denied; record the returned status/error without weakening the permission set to bypass the check.

Use the downloaded JSON cases for repeatable inputs. A successful HTTP response with the wrong value is a failure. A successful local SQL check does not prove routing, authorization, or response serialization.

8. Deliver and repeat the checks

Commit the .projection, implementation, and project-appropriate regression tests together. Record the permission-set change and generated specification used by the consumer. Build and deliver through the normal solution pipeline, then repeat the authorized/unauthorized API cases in the target test environment with its own token and service root.

For a real integration, add the data-access, error, retry, duplicate-handling, and transaction rules required by its behavior. This pure function does not establish those properties for a write integration.

Troubleshooting

Symptom	Check and correction
Operation missing from API Explorer/specification	Verify environment, projection identity, generation, and deployment logs
Signature/compilation error	Compare implementation with the actual generated stub and target version
Unauthorized response	Check token expiry, issuer/audience, and environment before changing code
Authenticated but denied	Check effective identity and projection permission assignment
Invalid parameter/request	Use the generated method, spelling, required parameters, and encoding
Spaces-only request rejected	Distinguish HTTP parameter validation from the PL/SQL null behavior
Unexpected whitespace/case result	Compare the exact input characters and agreed normalization contract

Exercise and solution

Exercise: normalize demo ho 014 without removing the spaces between words. Explain why the field-length limit from the configuration lesson is not enforced here.

Show the solution

The result is DEMO HO 014: TRIM removes ordinary spaces at the ends and UPPER changes case. No replacement removes internal spaces. The function has no length-validation rule, so a field’s separately configured 50-character limit does not automatically become this standalone service’s limit. Add a deliberate server-side rule and failure cases if the API must enforce that requirement.

Cleanup and verification status

Revoke the dedicated training grants and temporary client/identity access when the exercise ends, following the environment’s security-cache refresh procedure after revocation. Remove the service only through a reviewed solution change after checking consumers. Delete local tokens from the API client.

Status: 26R1 documentation-based walkthrough; generated IFS artifacts, Oracle SQL checks, authenticated API calls, and permissions have not been executed here.

Apply the secure server methods and concurrency and transaction checks before exposing a service. Use the PL/SQL performance guide when measurements show repeated database work.